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printf ("Hello") ; 



print "Hello" 



JSR printMsg 



say "Hello" 
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Changing Times 

AC's TECH for the Commodore Amiga was the first disk- 
based technical magazine geared toward high-end Amiga 
users and Amiga developers. It is now the only maga/ine of its 
kind available (or the Amiga. Recently, our only competitor in 
the technical market, Amiga World's, Tech Journal, announced 
that they would be ceasing production. You may think this ,s 
good news (or AC's TECH and for the most part, it is. But A W's 
Tech Journal was a good publication and helped to bring much 
needed support to the growing number o( Amiga program- 
mer and developers. Like AC's TECH. it brought \ aluablu 
insights into the inner workings of the Amiga. 

Filling the void 

AC's TECH will (ill the gap created by the loss of A W's 
Tedt Journal. We have stepped up efforts to gather much 
needed information from developers and from Commodore. 
We are also searching for members of the Amiga Community 
who wish to share their knowledge of the Amiga with others 
interested in the technical aspects of Amiga computing. We are 
going to work even harder to remain the best publication ever 
created (or the Amiga Technical Community. 

Over the course of the next few issues, you will see an 
impressive change in AC's TECH. We will feature more articles 
than ever before. TECH will provide the latest and best 
infoimation available to make your dream projects come true. 
It will feature a special section providing information on 
product development from start to finish. Moreover, it will 
show you how to bring your creations to market and how to 
make a profit from your Amiga. The new TECH will provide 
views from throughout the Amiga Technical Community. We 
won't let you down. 

Whether it's AC's TECH, Amazing Computing, or AC's 
GUIDE, you know can be sure that there is a hard working 
team behind those magazines looking out for your best 
interests and providing you with all the information you need 
to make your Amiga complete. 



Changing of the Guard 

Also with this issue, we say good-bye to a good tneild and 
co-worker, Ernest Viverios, Jr. Ernie has taken leave of the 
company to pursue other interests in the computer industrv 
I mie was part of the founding staff of Amazing Computing for 
the Commodore Amiga. I le has served as Associate Editor of that 
magazine as well as Editor of AC's TECH and AC's GUIDE. We 
will continue Ernie's tradition oi excellence that helped to 
make AC's TECH and its sister publications number one. We 
wish Ernie the best of luck in his future endeavors. 

Information Exchange 

Knowledge is the key to success. AC's TECH is dedicated 
to instilling you with the knowledge vou need to achieve 
optimal use of your Amiga. If you have created a program vou 
feel would be useful to others, know some tricks and short-cuts 
to programming, are a master at a particular language, or have 
an idea for an interesting hardware project, call us. Likewise, il 
you are an Amiga Developer and would like to share \ 0U1 
experience and knowledge with the rest of the Amiga Commu- 
nity, let us know! We are always looking for great article ideas, 
so share the wealth of Amiga knowledge and write for AC's 
TECH. 




Jeffrey Gamble 
Editor 
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PROGRAMMING THE AMIGA 
IN ASSEMBLY LANGUAGE 



MACROMANIA 

In the first article of this series we did a lot of extra writing 
when typing the programs. Most of this was repeating 
several key phrases over and over. A simple way lo cut down 
on all of this repetition is to use a Macro — sort of a glorified 
GOSUB routine. The two differences between macros and 
sub-routines are: 

1. A macro is repeated each time you call for it in Ihe pro- 
gram. This creates a larger program but lets the program run 
more uickly. I think it also makes the source code more 
understandable. 

2. Values can be passed to a macro very easily; you can even 
write your macro to assemble only part of itself depending on 
the value passed to it. You mav pass numbers, phrases, 
labels, etc to .1 macro, all with the same procedure. The key 
point to remember i> that a macro onlv affects the writing of a 
program, not it-, operation. Once ifs in the program, it won't 
change. 

The first line of a macro contains the title of the macro on 
the left followed by a space or tab and MACRO. The routine 
the macro assembles follows, typed as a regular assemblv 
program. Any branches and labels within the macro are 
written as NAMEN®. Finally, all macros must end with a tab 
and EN'DM (I \!> Macro) Pass values to the macro within 
the program by typing a tab, including the macro name 
followed by a tab and any variables to be passed, each 
separated by a comma These variables may be numbers, 
addresses, routine names, library routines, etc.; just separate 
each with a ",". The first variable is referred to within the 
macro by calling it "\1", the second is "\2", etc. 

It's a matter of choice whether you want to use the 
library offset names or- their actual values. I feel the program 
is more readable when using library names, but that does 
take some extra typing. Just trv to be consistent Macros can 
be very habit-forming. You can make them as complex as you 
want, and one macro may even call another. I wouldn't trv to 
be too "cute" with them. Even if no one ebe will be reading 
them, you will look back al a program written a few months 
earlier and wonder what you meant. Always include the 
values expected as a remark alongside the macro name for 
reference, In fact, I keep a separate notebook of all of my 
macros to include the name, what variables are expected, 
what registers il uses, what's required in the program, and 
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any other pertinent information. Even if it's just a one-time 
macro, I still record it; you never know when you mav need it 
again there's no sense in re-inventing the wheel 

Macros may be saved in a macro file to be used with any 
program. But since macros are so specific, it makes sense to 
save them in different files depending on with which major 
library they are used. In this way only the macros you need 
are called for at the beginning of the program with tab, 
INCLUDE MACRONAME.I. Since most routines need the 
EXEC Library, I made this my general macro file, and the 
majority of programs will include it. 

l \l ( M \( RON 

Let's take a look at Listing 1, EXEC MACROS. Notice 
that most of the EXEC Library offsets are included first. You 
could have all of the offsets for all of the libraries in one file 
and "include" il, but 1 like to have just the ones I need 
available and it's one file fewer Since memory types are 
important to several EXEC routines, I also define the tvpe of 
memory .md equate them to their numerical values Just to 
refresh vour memorv: 

Public memory — any available type (fast first, chip 
second) Chip memory — for screen displays or sound 

Fast memory — for arrays and variables; 

Clear — sets allocated memory to zero 

The first actual macro is called SYSLIB. It automatically 
puts the location of the EXEC Library address in register a(> 
Since this macro is used in conjunction with the next two 
macros, let's look at OPENLIB. To open the DOS Library, we 
need only typeOPENLIB DOS,DONE. This will store the 
library 1 name in register al, the lowest acceptable version (0) 
m register dO, and call the macro SYSLIB, passing the value 
Openl.ibrarv- The SYSLIB macro will then execute that 
routine returning the library location in register dO. OPENLIB 
will store that value in "dosbase"; the"M" is actually 
converted to read "dos" so "\ lbase" becomes "dosbase". If 
the library wasn't found, a zero would be returned and the 
macro would branch to the address in "\2" or, in this case, 
1X)\I" Already we've replaced seven lines ol commands 

with |ust one line! Ihe next four macros are necessary s.ince 
the current v erstori of A68K does not support a BLO (Branvh 
if LOwer) or BHS (Branch if Higher or Same) command; the 
macros allow you to use these commands replacing then with 
UK equivalent IK'S (Branch if Carry Set) or ISC (. (Branch if 
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PART II 



READIN', WRITIN' & 
RITHMETIC 



by William P. Nee 



Carry Clear) I he MEMORY macro will tell you how much of 
chip or fast memory is available, Finally, EVENPC will create 
a blank word value, forcing addresses lo start at a location 
divisible by four. There are other macros within this file but 
I'll wait until we actually use them before I discuss them. 
i opy Un-- tile trom the maga/me disk to tin- ASSEMBLER 
disk I discussed in Part I of tins series as EXECMACROS.I. 

IH>S MACROS 

Nexl lefs reviev. the IX* MACROS, Listing 2. DOSLIB 
will execute whatever DOS routine you pass to it. STYLE is 
our first example of conditional assembly II \t chei ks to sue 
if two strings are not the same; IFC checks to sec if they are 
the same. So the first line of the macro will look at the lirM 
value passed and if it is not zero, it will print in that style. If 
the value had been a blank followed by a comma (,2,3 for 
example) the 'M' would have been a blank and that part of 
the macro would not assemble. In the same manner the 
macro also checks for a foreground and background color. 
You could pass from one to three values as long as you have 
the commas separating them (NORMAI.,,3 for example). 
Notice the single quotes around '\1' convert it to a string. 

PRINT is .1 macro that prints a message just as 1 dis- 
cussed previously in Part I. You can either pass the message 
length as the second variable or omit it and let the macro 
compute the length. Since there can be only up to two 
variables passed, you don't need the comma if you just pass 
the message name. The macro PR1NTHEXR will print the 
contents of anv register in HEX format (Base 16) just as I 
discussed in Part 1 The only change I made is to save 
registers aO, and d0-d3 with MOV EM L (MOVE Memory), 
pushing them on to the slack, they are recalled in the same 
wa) at the end ol the macro, I'RINTDECR prints the contents 
of any register as an unsigned decimal number. A Hl-byte 
buffer is reserved at the end of the file and the macro stores 
ASCII values of numbers there from right to left. The number 
in d] is shifted left; the value in dO is rotated left and the left- 
bit from d I that went to the C and X bit in the status register 
becomes the first bit in dO. Using the ROXL.L command 
means to include that X bit as a replacement bit for the one 
lost during the rotate. Any lime dO exceeds a \ alue of 9, that 
value is decreased by 10. Since we're shifting dl. we can also 
use it as an exponent counter and add a I every time dO 
exceeds 9. This procedure continues for all M bits indl; then 



"S30 is added to the number in dO to get it's CHRS value and 
that value is stored as the right-most number in the buffer. If 
d 1 is clear, then that's the end of the routine; if not, the 
routine repeats the whole procedure, again putting the CHRS 
value in dO as the next number in the buffer. At the end of the 
macro the saved registers are restored to their original value. 

All of the following print macros use the CSI (Control 
Sequence Introduce) to print something. They start with 
<r$9B, or 155, and are followed by a value and a case-sensitive 
letter. Since PRINT needs to know the length of text, I 
included that with each of the macros. Notice that a macro 
can call a storage location with the same name— A68K won't 
get confused. For example, if you want orange foreground, 
the macro ORANGEFG prints the contents of "orangefg", a 
four-byte string (155,3,3, and m). The macro RIGHT will 
move to the right a given number of spaces and then print 
something. Copy this file to your ASSEMBLER disk as 
DOSMACROS.I. 

Before we use these two macro files, here are three short 
programs that will save you a lot of typing when you 
assemble and Blink your programs. Use ED, or a similar 
word processor, to create these script files (also included on 
the magazine disk): 



ASB 


ixon 




DSAVE 






KEY NAME 




KEY NAME 


KEYNAME 






A68K <NAME>.ASM 




COPY 


DF1:<NAME>.ASMRAN 




COPYNAME>.ASMDFl 


BLINK <NAME>0 






COPY <NAME> 


DF1: 




Dl 1 1 li - \AME>.0 







Save each of these files in the C director}' of the ASSEM- 
BLER disk. Next, add EXECUTE to the C directory and 
modify the S/STARTUP-SEQUENCE by adding COPY C/ 
ASB I DCOPY I DSAVE RAM: and COPY C/EXECUTE 
RAM:C/X; this aLso changes the EXECUTE command in 
RAM:C to just X. When you've finished typing your pro- 
grams, you can assemble. Blink and delete the "O" file with 
just one command by typing X ASB FILENAME To save the 
source code and assembled program from RAM: to DF1: type 
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X DSAVE FILENAME; to copy .in ".asm" file from DF l to 
RAM ivp.-xixon HI I WMf- You can modify these 

hree programs to suit vour own disk system and require- 
ments. And those of you with more advanced systems could 
create yOUI own shell commands or aliases along the same 

mes 

RKADIV X WRIT/IN" 

Now lefs taki- >i break and try out some of our macros 

Listing 3 is a program thai will let you know where the DOS 
Library is located and then prints two messages telling you 
how mudl available chip and fast memory you have. By 
using macros we will change the print styles, alter the 

ton-ground and background colors, and formal the printing. 
The first part of the program opens the IX>S Library. sa\ es its 
address, executes the DOS Output routine and saves the 
, unhandier address. In Tart I it took ten lines to do all of that! 

Next change the print style to boldface and print the 
"dos" message. After moving right eight spaces, return to 
normal print but reverse the foreground and background 
colors. After putting the DOS Library address in register dO. 
the PRINTHEXR macro will print the contents ot register dO 
in HEX format. Then it's back to normal printing and 
execution of a linefeed. 



Macros can be very 
habit-forming. 



_ 



The STYLE macro is then used to set italics type, orange 
foreground, and black background. After printing the "chip" 
message, the print reverts back to normal and the amount of 
chip memory is printed ten spaces to the right. The 
l'KI\ I HI C K macro will print the contents of register dO as a 
decimal number. After a linefeed, the same procedure is 
repealed for "fast" memory. White this program does three 
times as much as the one in Part I, it slill uses less lines. Try 
modifying the print styles and colors and see which combina- 
tions look better together. You could even create your own 
favorite combination macros — sort of like mixing ice cream 
flavors Copy or assemble these files to the PROGRAMS disk 
I discussed in Part 1 as MEMORY.ASM and MEMORY 

& RITIIMIIK 

Up to this point all ot the numbers we've been using are 
whole numbers. But life isn't as simple as 1+1*2, How does 
the Amiga handle a decimal fraction like 1.23457 It can 
convert all variables or numbers to a IIP (Fast Floating Point) 
format. There is a special MATHFFP Library that handles the 
math functions we'll need and, just like other libraries, has its 
own offsets, 



All numbers can be represented as a power of 2 using 
logarithms — the exponent is the power that the number 2 is 
raised to and the mantissa is the number in front of the two. 
For example, the number 9 in Base 2 is 1001 or .1001 "2 A 4, so 4 
is the exponent and, ignoring the decimal, 1001 is the 
mantissa (FFP format always uses a mantissa starting with 
.1). The floating-point number is put in the 32-bit data register 
dO by the SPFLT command. The mantissa is in the left-most 
24 bits (3 bytes) and the exponent in the first 8 bits (7-0). The 
left bit in the exponent (bit 7) is used for the number's sign — 
for positive and 1 for negative Also the value »S40 is added 
to all exponents. The only exception to these rules is zero — its 
value in FFP is always 0, in fact, 32 of them. To keep using 
our example, we said that the number 9 is .1001 "2 A 4 so the 
mantissa is 10010000. and the exponent is *S40+4. The entire 
number in floating-point format would be (90)(00}(00)(44(. 
One more example. Let's try -.0625. First that becomes -.0001 
in Base 2 or -.l*2 A -3. The mantissa is 10000. and the exponent 
is WS40-3. But since this is a negative number, we have to 
make bit 7 of the exponent a I so the entire exponent becomes 
BS40-3*«S80 or »$BD This number would then be in register 
dO as <10)(00)(00><BD). Every FFP number except must ha\ e 
at least bit 31 set. Adding or subtracting 1 from the exponent 
is ,i quick way to multiply or divide a non-0 number by two. 
To negate a number just reverse bit 7 {the sign); to get tin- 
absolute value clear bit 7. 

MATH MACRO 

Now let's discuss this new library, MATHFFP. It's 
opened in the same way as EXEC and DOS using the name 
"mathffp.library". Take a look at Listing 4 — 
SPMATHMACROS.L The "SP" means all computations are 
done with Single Precision, just as in normal Basic. The 
offsets for its functions have been added to the "offsets:" 
portion of the macro. In all cases, register dO contains the 
desired number along with, if necessary, register dl and the 
result will always be in dO. The math library functions are: 
SPFLT — converts a whole number in dO to a FFP number 
SPFIX — converts a FFP number in dO to a whole number 
SPCMP — compare FFP numbers in dO and dl; branch 
accordingly 

SPTST— test the number in dO; branch accordingly 
SPABS — makes the number in dO always positive (bit 7=0) 
SPNEC — multiplies the number in dO by -1 (reverse bit 7) 
SPADD— adds the FFP numbers in dO and dl; result in dO 
SPSUB— subtracts dl from dO 
SPMUL— multiply dO and dl 
SPDIV-<lividedObydl 

Many of these routines use registers dl, aO, and al in their 
computations so be sure to save any necessary data already in 
them. Of course you could try to program your routines to 
never need the data in these registers. 

Also included with this macro is the MATHTRANS 
Library- This library handles all of the trig functions (sine, 
cosine, etc.) as well as other functions such as exponent, 
natural logs, and loglO, square roots, and raising a number to 
a power. Again, the original value must be in dO and the 
result will be returned in dO. The function SPSINCOS returns 
not only the sine in dO but also the location of the cosine in 
dl. 
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I here are a few new terms in this macro. NAR< . repre- 
sents the Number of ARGuments passed by your program to 
the macro. NAKG, by Ihe way, in one of the lew case- 
sensitive words used with A68K; il must be all upper-case. 
1FEQ is a condiiion.il assembly meaning IF HQual toO. So, if 
NARC-2 is equal to 0, there must have been two values 
parsed to the macro and the next lines will assemble. How- 
ever, it NARC-2 was not 0. the assembly would skip to 
ENDC (END Conditional assembly) and start assembling 
after there. You're not limited u> II I Q. Other combinations 

are 

IFM it not equal (toO) 

IFG1 il greater than (0) 

IFGE— if greater than or equal (to 0) 

IFLT — if less the (0) 

IFLE —if less than or equal (to 0) 
lust remember that if the condition is false, assembly will skip 
to the next ENDC. Copy this file to your ASSEMBLER disk as 
SPMATHMACKOS I It von have enough memory you might 
want to modify the ASSEMBI I K VSTARTUP-SEQUENCE 
to copy these hies into RAM this will keep DHfc from coming 
on and off all the time. 

I Isting 5 is a math_demo that uses five of these macros 
FLT, FIX, MUI., DIV, and POW. Since these are all condi- 
tional macros you can either just call the macro or pass values 
to it After opening the DOS. MATHFFP, and MATHTRANS 
I lhraries. the program next converts two numbers to FFP 
format, stores them in Nl and N2 and then multiplies them; 
although three macros were used, no values were passed to 
them so the conditional parts were not assembled. In the next 
portion, two numbers arc converted to FFP format but, this 
time, the values Nl and N2 are passed to the DIV macro so 
Ihe conditional portions will assemble. In the last portion 
values are passed directly to the FLT macro and Nl and N2 
are passed directly the the I*OW macro. Having this type of 
capability allows for very flexible programming. In one 
portion you could pass number-, to a macro while in another, 
you can use labels. Copy or assemble these tiles to vour 
PROGRAMS disk as MATT I.DEMO.A5M and as 
MATH_DEMO. 

Notice that the DOSMACROS.I Me was also included Ln 
this program so you can take advantage of all of the DOS 
macros PRINT, PRINTDECR, etc. Of course, if you don't 
want to use any of them, just omit the macro file from your 
"includes'' If you would like to see how A68K has assembled 
your program, type A68K MATH_DEMO.ASM -L This will 
creat,- a new Hie in RAM: called MATH.DEMO.l5T. Use 
MORE to read this file The fir>t portion is the three include 
files I he program Itself starts at Line 604. You can see that all 
of the used macros haw been assembled. Notice the differ- 
ence between the MUI macro (I ine 667) where no values 
were passed and the DIV macro (Line 771) where Nl and N2 
were passed. The DOC files for A6SK are included on the 
magazine disk so von can read some of the different assembly 
procedures and get more information about the program 
itself. 



SAY WHAT? 

Since we've learned a little about readin' wntin' & 
'nthmelic — let's teach our Amiga to speak. This will involve 
using the TRANSLATOR Library and NARRATOR Device. 
The Translator will convert the text string into phonemes and 
store them in an output buffer. Then the Narrator will be 
activated as an IO (Input/Output) device and be given the 
task of speaking the phonemes 

To program a device, we need to accomplish four steps 
related to "tasks'' and "ports". Since the Amiga is 
multitasking, we tend to think of it as having several opera- 
tions running at once but. of course, only one task can be 
performed at a time. All tasks therefore are either currently 
running, ready to run, or waiting for a specific event to occur. 
The programmer can also ^ki a new task or remove an old 
one. Use the EXEC routine FindTask to find the task structure 
for a specific task by name or. by passing a 0. get the location 
of the current task structure in dO. 

Ports are used to collect and store messages. Since the 
Amiga is multitasking, any task can send messages to a port, 
but only one of these tasks will know when a message 
arrives, in our example we'll want to add a port for our task 
with the EXEC routine AddPort by passing a port storage 
location defined at the end of the program. We'll also uses the 



Always include the 

values expected as a 

remark alongside the 

macro name for 

reference. 



EXEC routine DoIO to start the device bv passing the 
lOrequest location. 

To summarize, we'll program our device by passing a 
to FindTask; use AddPort to create a reply port, and store the 
task returned by FindTask at the port address* 16. Then open 
the device with OpenDevice, enter the required values in the 
IOstructure. and start the device with DoIO (the program 
won't continue until the task is completed) or SendIO (start 
the task and then continue). 

Since almost everything in the Amiga is structured, let's 
spend some time discussing the lOrequest structure. The 
main advantage of structuring is that all required values are 
always a specific distance in bytes away from the start of the 
structure. This makes it easy to read or change values as long 
as \ mi know their offset distance. The standard lOrequest 
structure looks like: 

MESSAGE STRLimiRF 
next entry 
4 previous entry 

8 entry type 

9 priority 
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10 name 

14 replvport locition 

18 length 

IP REQUEST 

20 device 

24 unit number 

28 command ("2= read; #3= write) 

30 nags 

31 error status 

32 number of bytes transferred 

36 number of bytes to be transferred 

40 data buffer 

44 device offset 
I his is followed by the required values tor the given device. 
The NARRATOR Device requires: 

NARRATOR DEVICE (speech) 

48 rate 40-400 11501 words per minute 

50 pitch 65-320 [110] hertz 

52 mode [natural=0|, robot=l 

54 sex |male=0], female=l 

56 location of channel masks (33.10,12) 

60 number of masks (4) 

62 volume 0-64 [64 1 

M sample frequency 5,000-28,000 [22,200| 

66 mouth [0=off|, l=on 

67chanmask (assigned internally) 

68 numchan (assigned internally) 

69 padding 

The numbers in |] are default values assigned by Ihe device. 

TRA.NSI.ATOR MACRO 

Listing 6 is the TRANSLATORMACROSJ file that does 
most of the work for us. Since using the TRANSLATOR 
Library means we will also need the NARRATOR Device., 
I've included the set-up necessary for both in this file. There 
is only one offset in the library — TranslateText. This routine 
requires the address of the string to be translated in aO, the 
string length in dO. the buffer location where the translated 
phonemes will be stored inal and that buffer size indl. 

Next are the various equates. The two device commands 
Read and Write are defined, followed by the various speech 
parameters. The first macro OPENNARDEVICE opens the 
device by putting the device name in aO, the lOrequest In al. 
the unit number (0) in dO, and flag requirements (0) in dl. If 
the device can't be opened, dO will contain an error message 
number and the program must terminate. 

The other macro SAY will put all of the speech param- 
eters into their proper locations, compute the text string 
length, translate the text into phonemes, and speak them. The 
values for speech must be in the following order— text, rate, 
pitch, mode, sex, volume, and sample frequency. They must 
be in this order, but, since the macro will conditionally 
assemble them, you may omit any setting being sure to keep 
the ","- For example, vou could use SAY 
TEXT1,160„ROBOT„,20000. If you want to use only the 
default settings, just pass the text location; NARG will equal 1 
and the macro will conditionally assemble. Now you can see 
why 1 recommended keeping a record of all macros and what 
they require. Since various storage areas are needed, it makes 




sense to include some of them in the macro; the program 
doesn't care where they are located. This keeps you from 
having to remember a lot of extraneous material and lets vou 
concentrate on the program, so I've reserved space for the 
lOrequest structure in the file. It you have a very long text 
string, you may need to increase the buffer from its present 
size of 512 bytes. Copy this file to your ASSEMBLER disk as 
TRANSLATORM AC ROS. I. 

Our final program. Listing 7, is rather short, thanks to all 
ot the work done bv the macros. The program will speak 
three text phrases using different voice settings. After 
opening the TRANSLATOR Library, the lOrequest is set up 
for the NARRATOR Device. Then each text phrase is spoken 
using the values passed in the SAY macro. At the end of the 
program the port is removed, the device closed, and the 
libraries closed. Then space is reserved for the stack pointer, 
library and device locations, the port, the two text strings and 
their phonemes buffers, and the channel masks. Notice that 
the length is computed using """ which means "this loca- 
tion". Once the initial set-up is out of the way vou could use 
these macros to add speech to any program And it your text 
string was already converted to phonemes you wouldn't 
need the TRANSLATOR Library, but that's a lot of extra 
work. Copy or assemble these files to your PROGRAMS disk 
as TALK. ASM and TALK. 

RACK TO THE FLTURE 

Again, we've covered a lot of ground but 1 think that Ihe 
macro files will make programming easier for vou. Feel free 
to modify these files in any way you want. Be sure, however, 
to include these files along with the source code for any 
programs you write for someone else or have published. In 
the next article I'll discuss the INTUITION and C.FX Libraries 
and we'll write some graphic programs using arrays and a 
quick PSET routine. 
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Resource macro disassembler — NEW VERSION! 

Resource V5 is an intelligent interactive disassembler lor the Amiga programmer Resource V5 is Dlindtngty tasl. disassembling literally 
hundreds ot thousands ot lines per minute from executable files, binary tiles, disk tracks, or directly from memory. Full use is made of the Amiga 
windowing environment, and there are over 900 (unctions (o make disassembling code easier and more Ihorough than its ever been. 

Virtually all V2.0 Amiga symbol bases are available at the touch of a key In addition, you may create your own symbol bases. Base-relative 
addressing, using any address register, is supported lor disassembling compilod programs. All Amiga hunk types are supported for code scan. 

Resource V5 runs on any 680x0 CPU. but automatically detects ihe presence of an 020/030 CPU and runs taster routines II possible. 
Resource V5 understands 68030 instructions and supports the new M68000 Family assembly language syntax as specified by Motorola lor the 
new addressing modes used on the 020/030 processors Resource VS and Hacro68 are among the few Amiga programs now available that 
provide this support. Old syntax is also supported as a user option. 

An all new online help lacility featuring hypertext word indexing is included. This enables you to get in-depth help about any function ai the touch 
ol a keyl Resource V5 includes a new. completely rewritten manual featuring two tutorials on disasssembly. and comprehensive instructions lor 
utilizing the power in Resource V5. 

Resource V5 will enable you to explore the Amiga Find out how your favorite program works. Fix bugs in execuiables Examine your own 
compiled code. 

"If you're serious about disassembling code, look no further!" 

Resource V5 requires VI .3 or later of the Amiga OS. and at least 1 megabyte of ram Resource V5 supercedes all previous versions 



Suggested retail price. USSI50 



Macro68 macro assembler — NEW VERSION! 

Macro68 is the mosf powerful assembler for the entire line ot Amiga personal computers 
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MacroSB supports the entire Motorola M68000 Family including the MC68030 and MC68040 CPUs. MC68881 and MC68882 FPUs and 
MC6885I MMU. The Amiga Copper is also supported, eliminating the need for tedious hand coding of 'Copper Lists' 

This fast, multi-pass assembler supports the new Motorola M68000 Family assembly language syntax, and comes with a utility to convert 
old-style syntax source code painlessly. The new syntax was developed by Motorola specifically to support the addressing capabilities of the 
new generation of CPUs. Old-style syntax is also supported, at slightly reduced assembly speeds. 

Most features of Macro68 are limited only by available memory. It also boasts macro power unparalleled in products of this class. There ate 
many new and innovative assembler directives For instance, a special structure offset directive assures maximum compatibility with ihe Amiga's 
interface conventions A Irame offset directive makes dealing with stack storage easy. Both forward and backward branches, as wen as many 
other instructions, may be optimized by a sophisticated N-pass optimizer Full listing control, including cross-referenced listings, is standard. A 
user-accessible die provides the ability to customize directives and run-time messages Irom the assembler. 

Uacro68 is fully re-entrant, and may be made resident. An AREXX" interface provides 'real-time* communication with the editor of your choice A 
number ol directives enable Macro68 to communicate with ArmgaOos" External programs may be invoked on either pass, and the results interpreted. 
Possibly the most unique feature of Macro68 is the uso ol a shared -horary, which allows resident preassembled include files lor incredibly fast assembles. 

MacroSB is compatible with the directives used by most popular assemblers. Output file formats include executable object, linkable object, 
binary image, and Motorola S records Macro68 requires at least 1 meg ol memory 

Suggested retail price. US$150 
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Amiga Voice 
Recognition 



by Richard Home 



One of the most interesting and difficult tasks to be under- 
taken by modem computer science is that of recognition of 
human speech. Special purpose (and expensive) hardware is 
available commercially that provides fixed vocabulary speech 
recognition in real time. Now there is available a public domain 
disk-based Amiga library that will permit Amiga programmers 
to add voice recognition to their applications using the Perfect 
Sound 3audiodigili/er. This voice. library provide* functions lor 
learning and recognition of user-defined words or phrases in 
near real time using any Amiga computer. 

How Con a Computer Recognize Speech? 

Two primary methods of computer voice recognition have 
been studied extensively. These can be called speaker indepen- 
dent and speaker dependent voice recognition. Both operate on 
digitized samples of human speech and attempt to match re- 
ceived speech samples against characteristics of a fixed vocabu- 
lary. 

Speaker- independent voice recognition is the more general 
approach. This technique requires the computer to analyze a 
received speech sample against statistical vocabulary character- 





istics derived from a large population of individuals This tech- 
niquecan in theory recognize the same wot dor phrase spoken by 
different individuals and account for differences in speech ac- 
cent, pitch, and speed. In practice, this technique requires so 
much processing power and time that it is not practical for use 
with most desktop computers. 

Speaker-dependent voice recognition is more practical for 
our use 1 his technique requires thai the individual user prm ide 
digital samples of his/her voice for each word or phrase of the 
desired vocabulary. The characteristics of these samples are 
stored in memorv. Characteristics of incomingdigitized words or 
phrases are then compared against these to find the best match. 
The disadvantage of this approach is that only the speech *•( one 
individual will be recognized. The advantage is lhat the tech- 
nique is relatively fast and accurate. 

What Is Voice.library? 

Included on disk is .1 copy of Amiga voice. librarv 83 well -is 
Voicelibrary.doc which documents each of the library functions 
It voice. librarv is copied into your sysrlibs directory, your pro- 
grams will be able to access its functions to easilv implement 
speaker-dependent voice recognition. 

As might be expected, the primary functions 
contained in the library to assist in voice recognition 
are the "learn" function which samples and stores 
characteristics of the user's voice for each vocabulary- 
word or phrase, and the "Recognize" function which 
comparescharactensticsof incoming digitized speech 
against the learned vocabulary to produce a match. 
The principles of operation of these primary func- 
tions are explained below. 



Learning a Word 

In order to learn, or store characteristics ol 

vocabulary words or phrases, a decision must he- 
made as to what characteristic of speech is to be used 
lor recognition. Many different techniques ha vebeen 
tried including phoneme-base.! systems which at- 
tempt to divide incoming words into distinct and 
unique sounds (phonemes), as well as systems which 
examine the frequency and amplitude of the incoming 
signal as a function of time. Hor simplicity and speed, 
the technique used by voice.library is to determine 
the frequency content of the spoken word or phrase 
o\er a period of time. This frequency spectrum infor- 
mation is stored in memory as a frequency map for 
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later use in recognition of incoming words. The learned vocabu- 
lary consists of a stored sequence of these frequency maps, each 
associated with one word or phrase of the vocabulary. 

In constructing a frequency map, tradeoffs are necessary 
between frequency resolution and time span allowed (or each 
word or phrase. We need the highest resolution frequency analy- 
sis available that is consistent with the time scale of the incoming 
word or phrase and that can be computed in near real time on a 
standard Amiga. The compromise chosen for use with voicc.library 
is tocomputea frequency analysis at 72 points in time over a span 
of 3/4 of a second. For each of these 72 points, 32 frequency data 
points are computed corresponding to frequency content in 32. 
100 Hz bands from Hz to 3200 Hz. This compromise limits the 
length of learned words to 3/4 second, but this is adequate for all 
but the very longest words. Also, 
only frequency data below 3200 
Hz is utilized directly in voice 
recognition. However, the 
strongest frequency compo- 
nents of human speech are gen- 
erally below this limit. 

Before calling the "Learn" 
function, the user must decide 
on a sequence and number of 
vocabulary words or phrases to 
be used. Then each vocabulary 
entry is learned according to the 
following synopsis: 



Word Recognition 

Recognizing a word requires exactly the same process as 
learning a word. That is. .» frequency map of 3/4 seconds of time 
is computed for incoming words. Then, using a pattern recogni- 
tion algorithm, this incoming map is compared with every learned 
map in the vocabulary. A synopsis of the "Recognize" function is 
as follows; 






Recognize (HapButter. Vocabulary, Resolution) 

0.Q dO dl 



MapBuffercontainsa sequence of frequency maps produced 
by "Learn" corresponding to each word or phrase in the vocabu- 
lary. Mapbuf fer address is passed to "Recognize" in aO. Number 
of words or phrases in the vocabulary arc passed to "Recognize" 

in dO. 



N 



HapAddress ■ Learn iKapBuffer. 
Text, Screen, Sequence, X. Yi 

dO aO 

al a2 dO dl di 

Each frequency map is 
made up of 72 long words of 
data — each representing 32 fre- 
quency points — plus a 16-byte ^ ^^^^^^^^^^^^^^^^ S? 
header for the associated ASCII 

text (304 bytes total). "Learn" requires the user to reserve a 
MapBuffer in memory equal to the size of vocabulary desired 
(number of words or phrases) times 304 bytes. The MapBuffer 
address is passed to "Learn" inaO. Address of a null terminated 
text string representing the word or phrase lobe learned is passed 
to "Learn" inal. 

The "Learn" function will open its own window on the 
screen specified in a2 at a position X, Y specified in dl and d2. The 
user will then be prompted to speak the specified word or phrase 
to obtain three good digital samples. Internally, these three 
samplesareanalyzed for frequency content and transformed into 
a frequency map (304 bytes) which is stored in the MapBuffer in 
order, according to the sequence number specified in dO. "Learn" 
returns the memory address within MapBuffer at which this 
particular frequency map is stored. 

"Learn" is called separately for each word or phrase in the 
vocabulary. After every word or phrase has been learned, 
MapBuffer will be filled with a complete sequence of frequency- 
maps for later use in voice recognition. See voicelibrary.doc on 
disk for a complete description of this function. 



In constructing a 
frequency map, 
tradeoffs are necessary 
between frequency 
resolution and time span 
allowed for each word 
or phrase. 



"Recognize" listens for an 
incoming word, computes its 
frequency map. and compares 
this map to the sequenceof maps 
contained in MapBuffer. The 
Sequence Number of the word 
or phrase in MapBuffer which is 
most similar to that of the in- 
coming word is returned in dO. 
Note that the number "0" repre- 
sents the first word, " 1 " the sec- 
ond, and so on. See 
voicelibrary.doc on disk for a 
complete description of this 
function as well as various er- 
rors that might be encountered. 
"Recognize" will operate at 
either high resolution (d 1 = 0) or 
low resolution (dl = 1). High 
resolution computes a fre- 
quency analysis of the incom- 
ing word or phrase at 72 points 
in 3/4 second whereas low 
resolution computes only 36 points in 3/4 second. High resolu- 
tion is somewhat better at word recognition, but takes almost 
twice the processing time. 

Multitasking Word Recognition 

In many applications it will be convenient to have the "Rec- 
ognize" function operate in the background as a separate task 
under the Amiga's multitasking operating system. Voice.library 
provides this capability with the "AddVoiceTask" function. A 
synopsis of "AddVoiceTask is as follows: 

AddVoiceTanV (HapBuffer. HsgPort. Vocabulary. Reaolutionl 
aO al dO dl 

"AddVoiceTask" is similar in function to "Recognize" ex- 
cept that here, a separate task is started which listens for incoming 
words or phrases and returns messages to the user's Message 
Port indicating the Sequence Number of the frequency map in 
Mapbuffer which best matches the frequency map of the incom- 
ing word. MapBuffer address and Message Port address are 
passed to "AddVoiceTask" in aO and al. Number of words or 
phrases in the vocabulary are passed to "AddVoiceTask" in dO. 
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The messages sent to Message Port are designed lo mimk 

I1X Ml' messages with im_Class -- SO rhus vou can receive .mil 
process these im'-M.iy- M either .in Intuition window UK MI' 

message port or at a custom message port of your own. The 
im_Code for these messages consists of the sequence number of 
the frequency map in MapBuffer that best matches the frequency 
map of the incoming word or phrase. See voicclibrarv.doc on disk 
for a complete description of this function and the various errors 
that might be encountered 

A Pickle. Anyone? 

TheVoiceDeflwprogram on disk gives an exampleof the use 

of voicc.library for learning and recognition of words. Entire 
assembly source code lor this demonstration is contained in 
VoiccDemo.asm. This program is a simple illustration of the use 
ofvoice.librarytocreateandr«ogni/e a vocabulary consisting or 
the six phrases. "Peter... Piper.. Picked A Peck Of... Pickled 
Peppers." VoiceDemo uses the voice. library- "Learn" function to 
store a frequency map of each phrase, and the "AddVoiceTask" 
function to listen for and recognize incoming phrases. The Amiga 
Utilities "Say" function is used to repeat the phrase back to the 
user A plot of the frequency map of the incoming phrase is also 
displayed. Key sections of the assembly code are described 

below. 



* 



Two primary methods of 
voice recognition have 
been studied: speaker 
dependent and speaker 
independent* 



First, library' offset values must be defined tor voice library 
functions. These values are defined lor .ill (unctions In 
voicelibrary.doc on disk Onsets tor the primary functions used 
in VoiceDemo are defined .is follows: 






Access to voice.librar) is established using the Exe< 
"Openl.ibrary" function. Then library functions may be willed as 
subroutines using these offsets from the library base address 

Todcfine the desired vocabulary, I have listed each phrase of 
the vocabulary in order in a "WordList" Then each phrase of the 
vocabulary is assigned in order to menu items making up a 
complete "Learn" menu When the user Selects •• vocabulary 
phrase from the "l.eam" menu. VoiceDemo executes the following 
routine: 



■ 



■ 

.'Scrooi: 

'■a it ion 



\l, ipHulfer consists ot an area of memory ecjiial to the number 

ol vocabulary entries (six) times the size d each frequency map 
(304 bytes) l he sequence number of the word to be learned is 
defined by the number ot the menu item from the "I earn" menu 
selected by the user (ItemNumber). InfoScr is the St reen address 
of the background information screen on which the "I earn' 
window will open. The position of the "Learn" window is specified 

lobe \ 1 V V 40. 

This I earn Routine is called lor each phrase In the vocabu- 
lary by user selection ol the menu item corresponding to each 
phrase. Atter all phrases have been learned. MapBuffer is filled in 
order with a sequence oi six frequency maps corresponding to 
each oi the six phrases ol the vocabulary. 

Next, the user ma\ select "Recognize Word" from the project 
menu Votcel Vino n ill open a small "Voice Window" having an 
IDCM1* message port and then call the voice. library 
"AddVoiceTask" function to recogni/e incoming words mu\ 
send message- to the message pH'rt when a word or phrase is 
recognized A partial listing ot this routine is as follows. 

Recogni/.eRoutine 

■ 

window 



(ntiVP.1 

■ ■■ ■ 

■ '.' 

I 



■ 



■■' I'-.atl 

- ■.' i 

WclJ/Bf ; 



' 



movea.. 



■ 



■■ 
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VoiceWdw is the Intuition Window definition (including an 
11X Ml' message pori at wd .UserFort) for receiving messages 



when words are recognized. MapBuffer contains the frequency 

maps previously learned Resolution ha*, previously been de- 
nned by user menu selection as "0" for high resolution or "1" for 

low resolution frequency mapping. 

When "AddVoiceTask" is called, background voice recog- 
nition begins. VoiceDemo may then "Wail" for message?, to be 
recei\ ed at the message port ot VoiceWdw. Note that either Voice 
messages or Intuition messages may be received at the same 
message port. These can be separated upon receipt by 
MessageClass. Only Voice messages have MessagK lass SO 
Message* ode equals the sequence number of the recognized 
word based on the order in which word frequency maps have 
been learned and stored in MapBufler 

VoiceDemo proceeds from this point to pint the frequencv 
map of recognized words in the VoiceWdw and to repeal the 
recognized phrase back to the user using the "Say" routine. See 
the complete listing VoiceDemo.asm on disk for further details 
The frequency map plot is meant to graphically illustrate the 
structure of this map as used for voice recognition. Each map 
consists of 72 vertical lines (36 in low resolution). Each vertical 
line is made up of 32 points representing frequency ion tent in 32, 
100Hz frequency bands on the virtual avis The horizontal axis 
represents3/4 second of time. Tins plot is in effect a low resolution 
voice print of the recognized word or phrase 

Practical Considerations 

Choice ol vocabulary words or phrases is important to 
successful use of voice.library. Words that sound distinctly dif- 
ferent from each other will be more reliably recognized. If the 
words "tension" and "pension" are in your vocabulary. "Rec- 
ognize" will frequently confuse the two. 

Even with distinctly different words, you must be careful to 
pronounce all syllables of each word distinctly and forcefully. I or 
those of you with children, speak as if you are telling jroui 
offspring for ihe third time to "CLEAN UP YOUR ROOM!" Thif. 
is about the proper level of distinct and forceful speech. 

"Learn" and "Recognize" are sensitive to any change in the 
pitch or rate of your speech. If you havea cold, or are under stress 
such as when demonstrating your amazing program toa dubious 
mate, changes in the pitch or rate of your voice may confound 
voice recognition lima) be necessan, to relearn difficult words 
under these conditions. 

Voice recognition will be confused by background noise 
Humans can frequently nine out distracting background noise, 
but voice library cannot be that sophisticated. If hart Simpson's 
voice is coming from a television in the background, don't be 
surprised at Ihe results. 

Microphone selection can be important. Since frequency 
mapping in voice.library only uses a frequencv band of 3200 Hz, 
a super high bandwidth microphone is not necessary or desir- 
able. It can be helpful to have a microphone with a push button 
on-off switch. A microphone that is active all the time will 
sometimes trigger the "Recognize" function with stray noise 
rather than with the start of a spoken word. 

And finally, limit your vocabulary to the minimum required 
The maximum capacity of voice.library is 64 words or phrases 
I low v\ er. recognition time increases with vocabulary size, not to 
mention the time required to "Learn" every vocabulary entn 







The BASIC For The Amiga! 



ne BASIC package has stood the test of time. 
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Conclusion 

Voice.library is the result of several years of related work 
including the earlier public domain program "Amiga Spectro- 
gram'' for frequency analysis ol audio data. Voice.library was 
written to demonstrate the power of the Amiga and to entourage 
programmers to develop even more interesting applications of 
Amiga audio. The author will be happy to answer any questions 

or discuss your ideas for use ol voice library I le can be reached 
on-line as follows 

COMPUSERVE 71777.407 

CENIE RHORNE 

PORTAL RHome 

Your comments or suggestions for future improvement are 

also welcome. 
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Pleas* writ* to: 

Richard Horn* 

c o AG's TECH 

P.O. Box 2 140 

Fall River, MA 02722-2140 
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Dynamically Allocated Arrays 



By Charles Rankin 



There 1 was in the depths of writing a program and 
realized I needed to use some two-dimensional arrays. No prob- 
lem, I thought. Then 1 realized that I needed to be able to allocate 
these arrays to any dimension — on the fly— at runtime. Uh, oh. 
Now I had a problem. I dugout my trusty C references and began 
looking. "Won't be long now," I thought. Needless to say. after 
many hours of searching I didn't find anything. So I went down 
to the local bookstore to examine a few more books. Still nothing. 
It was obvious that if this was going to work, I was going to have 
to make it work. So I sat down with my handy-dandy C compiler, 
a pencil, paper, a tall glass of cola and some chips and came up 
with the technique below. 

Everybody knows about arrays, but not everybody 
knows that you don't necessarily have to specify their size when 
you compile. Take, for example, these two one-dimensional 
cases: 

Al 1-dimension; turd coded artsy size, 
•include •atdio.h» 

void malnO f 

int square 1 9]; /' declare array of sue 9 */ 

/• counter ■/ 
(or u * 0; i < 9; --i 
squared! t • 1 /• calculate square 

(or (i • 0; i < 9; ••!> 

printf {•%d\n'.squared)W '■ output array ■/ 
I /• end Mil - 

Bl 1-dimension: dynamic array size, 
■include <atdlo.h> 
void Mini) I 

int 'square . NULL; '• declare pointer for our 
array/ int i; ' X -" 

/" allocate memory tor our array '/ 

if | (square - lint •lmalloct9 " aueof (int 1 1 ) .-HULL) 



print (('Could not allocate 
sIXltlvr: 



irvivn-j) 



■ 



-ulate square */ 



for U = 0; I 
square 

-. ■■ 
print! CldVn", square]. I > ; /* output array •/ 
free (square > : /• free allocated n emcry "/ 
• md rain •' 

Both of these programs will produce the same output: a 
list of the squares of the numbers to 8. The first piece of code is 
very straightforward. The second piece of code may need a little 
bit of explanation. The call to malloct) allocates enough memory 
to hold 9 integer variables. The variable, square, holds the pointer 
to this information. It may seem strange thai we are accessing the 
information held by this pointer with what appears to be an array 
access. To understand this, you need to realize that the compiler 
translates the array reference squarc[i] into the pointer reference 
"(square ♦ i). Thus any array reference is translated to a pointer 
offset into the memory we allocated. 

Things are a little different when you gel into two 
dimensions. A little more setup is required to achieve the same 
goal. The following pieces of code show a two-dimensional 
example. 

A} 2 -dimensions; hard coded array size 
•include <stdio.h> 
void maim I 

int sumsquare ) 1 [ ; *. • :.-.-Iare 10 X 10 ar: I 

int l, • • 

for n 10; "li 

• 

auMquareliK)! * ■ till array •/ 

for (1 ■ 0; 1 < 10; --; ' loop through array *' 

for (j > 0; J < 10; .•]> 
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'.sionaquit!- ■ 

I /• er.d : Loo| ■ 



B) 2-.; 
< 
void m i 

rr«y •/ 

•l—i mi • 

■ 



BUO*qu«re!' 
■ 

. [Ml ■ ■ • . . 

■ ■ 

' ■ 

... 

•loop I 



Everybody knows about arrays 
but not everyone knows you 
don't have to specify their size 
when you compile. 



■ 

ElMJd • 

-oop "/ 

This program initializes a 10 X 10 array. It then stores in 
element Minisquarejrow|[coiumn] the sum til row squared and 
column squared. As before, the lirsl piece ot code is verv straight- 
forward The initialization ot the second piece of code is a little 
harder to see. First we allocate enough room (or 100 integers ,md 
lOintcger pointers- Then what essentially happens is we partition 



the 100 integer*, into lit separate 10 integer groups and point one 
of the integer pointer-, to each of the groups, This way when we 
.u v ,ss -.umsquarehllj], the sumsquare|i| part points to one of the 
integer groups and the |j) part references a specific integer within 
the group. Ina concise manner thearray reference sumsquare|i]lj| 
i> converted into the pointer reference "('(sumsquare * o <■ j). 

I think another small example would help to under- 
stand the initialization process. I ake this 3X3 example below. 
I et s tall the array test (actually test is an ml "). It may help to 
refer to the code ol section B) above with the array reference 
sumsquare changed to our new variable test 

\ole that a "-" in the contents field represents unknown 
Contents. These contents are unknown because we don't know 
wh.it was in the memory allocated bv malloc. 
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The first part tit the allocated memory contains the row 
pointers intoeach row of data in memorv. Note that since we were 
using a 3 X 3 array we use only indices through 2 when 
referencing array locations. So why then did we access test{3] at 

all (on the address line above)? Ihe reason is that this is actually 
the first part of our data storage. It is the first location alter our 3 
row pointers. And in reality we u anted only the address of this 
memory location sothat we could point row zero at it, this is the 

reason for the & (address) operator The same argument applies 
itir the access of tcst|0)[3|. The test|0] portion is .1 pointer to the 
actual data. Looking at testfOj,weseethat (headdress is "> I hen 
the [31 portion (of test|0)|3|) takes us3 places farther into memory 
(oraddressfe). This is where data for row 1 will start— remember 
we start with row 0. Thus we need the address of it, which again 
explains the & operator). 

We then initialize Ihe row 2 pointer with test(2] = 
&test| 1 J[3|, which sets data storage for row 2 at address « (test| ] ] 
= 6, test[ 1 1|3] goes 3 further, or address 9). We have now finished 
all our initialization and the array can be used likeany other This 
correlates to completing the for loop in the ci*ie of section B) 
above. 
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The above examples lead to a procedure which will 
allow you to allocate a two-dimensional array of any size that you 
wish. See Listing 1 for this procedure. Note that Listing 1 is 
specifically for arrays of integers. You could define this proce- 
dure for any type of variable also, be it float, double, short, char, 
or whatever. It would also be possible to define a macro that 
would allow you to define any type of array at any time (Listing 
2). The technique described here is also amenable toarraysof 3 or 
more dimensions; one must simply initialize another level of 
pointers. Also, take careful note that the array indices ••till start at 
as they do in regular arrays. 

I believe this technique is very beneficial inany program 
that uses arrays. If the user has only small requirements for the 
program then he does not have to be burdened with the extra 
memory required by the hard-coded arrays that the programmer 
used. On the other hand, it allows users with big demands and 
lots of memory to use that memory instead of being confined by 
the hard-coded array sizes the programmer used. I hope some of 
you out there can benefit from this technique as much as 1 have. 



• 



"Listing !■ 



A staple program chat asks the uaer lor the dimensions 
of a 2 dimensional array and then prints out the aunt 
of the tow squared and the column squared for each 
•tag ■• • . 



Illustrates the use of the procedure for dynamically 

allocating arrays. 

Authort Charles Rankin 

Compiles with Lattice C v5.05 (1c -L program name! 



• include- itdlo.h - 



" init_erray - procedure to allocate memory for a •/ 

/■ 2 -dimensional •/ 

/• the poiiv. 

' KJTE: even though the array Is of size y by x. V 

/* the indices are still only to |y 

/• and to lx-11. 

/ 

iM ••m;t_array(y. x) 

Int y.x: /* the t of rows and colunnB reap- 

I 



'• If we don't get the p 

NULL I 






'• eld- ■ pointers •/ 

else i 

■ 

array! . 

■ 

• -nd of the if const r-. 
I /• end of proco-*. 

void - 



mi •• * ■ : to our ai 

- = Oi * how ■ .n <irray */ 

tnc column • 0: . . uray •/ 

while 

the mummer ol r»rs in - 

scant i ■• :' 

It irov ■• 0) I /• user wanted to <; 

. ■ 
exit It . 

I 

. 

ncanfl-M*. fccoluani; 

/" don't reallocate memory • 

i! (square' 

'■ call procedure to in 

If ((square* 

ford ... 

..-■.; 

'• calculate sum of squares ■/ 
squares 1 1 i ; 

pr m' :-■■;-. - , ,•■ • itput ■ 

oop *l 
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. . . 



• ■ 



■Listing 2> 



\n _ ); 



wanted to gull ■ 
it taqu 

■ 
I 

■ '-h* number of column in* 

sc«nH*%d*. 

■ '-mory * ' 
if (squares! f ree (squares) ; 



/•A alible program that asks the usi ! • 

'• of a 2 dimensional array and i 

/' of the row squared and the column squared for each 



/" Ci 

I ires, int, row. column); 

, ,:■ N 

: JW: !••) i 



/• Illustrates th* uoe of a macro for dynamically 
/■ allora'.ng arrays. 
'• 

i* Aut r • .i- Rani 
/• Compiles with Lai * 




0: 3 < column; ]••) ( 
/* calculate bibb of squares V 



f output V 



) /• end j loop •/ 



■ lnclud) 

i.— nmm. nmt" of 

■Die type "type* with dimensions -y * "«•, 
" and *x" could even be exprna.v.i 

/* M< . towc aor type r«< 

/" want it to be, like short, long, unsigned char. 

'* float, or even int *. 



. . . . 

) /• end i loop */ 
■1b* printf I nor allocate memory for arrayl\n*| ; 

\ /• and whl 

• ■ 



'.type.-, 

C| (yl ■( <*> • r.iieof <typel.\ 



tiaa • 

■ name ill - (type *)'■■ <x) |;> 







I 

Int "= : ■ -, ■ ■ ■ array */ 

' hOM r<ir,y tows in ar; 

int column /• how many columns in array */ 

int i. ■ - <jummy loop variables •' 

while (1) I 
printf CinPltaw enter the number of town in* 
* the array 10 to q>; 
■*d*, btowlj 
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Amaze Them Every Month! 

Amaztttg Computing Tor The Commodore Amiga is dedicated to Amiga users 
who want to do more with their Amigas. I : rom Amiga heginners to advanced 
Amiga hardware hackers, AC consistently offers articles, reviews, hints, and 
insights into the expanding capabilities of the Amiga. Amazing Computing is 
always in touch with the latest new products and new achievements for the 
Commodore Amiga. Whether it is an interest in Video production, program- 
ming, business, productivity, or just great games, AC presents the finest the 
Amiga has to offer. l r or exciting Amiga information in a clear and informative 
style, there is no better value than Amazing Computing . 



A Guide For Every Amiga User. 

Give the Amiga usei on your gift list even more information with a SuperSub 
containing Amazing Computing and the world famous AC's GUIDE To Tlte 

Com mo it on- Amiga AC's GUtDl (published twice each ve.ir) is a complete 
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vast reference to the Commodore Amiga is divided and cross referenced to 
provide accurate and immediate information on every product for the Amiga 
Aside from the thousands of hardware and software products available, AC'S 
GUIDE also contains a thorough list and index to the complete Fred Fish 
Collection as well as hundreds of other freely redistributable software 
programs. No Amiga library should be without (he latest AC's GUIDE. 



More TECH! 

AC's TECH For The Commodore Amiga is an Amiga users ultimate technical 
magazine. AC's II CH carries programming and hardware techniques too large 
or involved to fit in Amazing Computing. Each quarterly issue comes complete 
with a companion disk and is a must for Amiga users who .ire seriOUSl) 
involved in understanding how the Amiga works. With hardware project-, such 
,1- t reating your own grey scale dtgiti/er and software tutorials such as 
producing a ray tracing program, AC's TECH is the publication for readers to 
harness their Amiga to fulfill their dreams 
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Implementing 

an ARexx Interface in your 

C Program - Part 2 



by David Bhckwell 



Since we got most of the hard work done in the first article, this should be short and sweet. We 
left off with a functioning program with only a minimal ARexx interface. The program, while 
a completely functioning, was not very functional. Well, even after we are finished with our ARexx 
interface, the program will still be barely functional. However, the purpose of this article was to 
introduce you to what is required to add an ARexx interface to your program. If you continue with 
the program, adding improvements and ending up with an excellent utility, then you have received 
a bonus. That is up lo you. 

As promised in the last article, I continued my testing of the rexxapp. library to see why the 
SendRexxCmd did not appear to execute synchronously as implied by the document file included 
with the library. During my test, I also discovered that the SyncRexxCmd exhibited the same 
behavior. 

In true synchronous execution, the function called should not return until all processing is 
complete. This just was not the case with the two previously mentioned functions. They seemed to 
return immediately, causing problems in my code following the function call since it was expecting 
to use the results returned by the functions. 

let r t ,l,iii of Dissidents Software, author of the rexxapp. library, was kind enough to provide me 
with a copy of the library source code. This answered all the questions I had about the routines. They 
package the request in an ARexx message and send it off and then return control back to the calling 
program. When the ARexx message returns, these routines call another function— the function you 
provide in the case of the SendRexxCmd and an internal function in the case of the SyncRexxCmd— 
and consider this the synchronous portion of their execution. I consider this pseudo-synchronous at 
best, as your program will have to be prepared to continue execution directly after the function call 
without the necessary return values you need to continue your work. This is essentially the same as 
asynchronous execution. 

Back to the Interface 

I also promised to add more commands to the RcxxData structure and I have again kept my 
promise. 1 added a total of eight commands. Three of these commands were already available in the 
host application. 1 just made them accessible through the ARexx interface. Three other commands 
are available only through the ARexx interface. These commands are used to provide information 
to the ARexx macros about the currently active file. This information is constantly available to the 
host application through global variables; therefore, the host application has no need to call these 
functions. Only two new commands were added to the program that arc called by both ARexx 
macros and the host application. 

These two new commands allow you to add entries to the database files created by the save 
command and to view selected entries in the files by searching the key fields in the file. I added these 
commands using two completely different approaches. The first way shows you how you can add 
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commands to your program by adding a function to the host 
application and then making it accessible through the ARexx 
interface. The second method uses an ARexx macro to provide a 
new command and then shows how to access it in ihe host 
application 

Adding Commands to the Host Application 

The first method is really nothing new; you add a function to 
the host application as vou would anv other program. You add a 
new menu selection, update vour switch code to receive Ihe 
intuition messages pertaining to the new menu selection and add 
the function(s) needed to implement Ihe new command. To make 
it accessible through the ARexx interface, add the command 
name to the KexxData structure, add one to the NUMCMDS label 
and add the rexx routine to call the new function. I will demon- 
strate how to call a function in the host application later when I 
discuss modifications I made to the dispatch (unction. 

ARexx Macros as Commands 

First you might ask. isn't thai what you normally do with 
ARexx macros? To that question I would have to answer, yes. so 
I will. That is what you do sort of. You can use ARexx macros to 
extend thecapabililiesofaprogramby adding commands tin- host 
application does nol have, Mm is not exactly what I am doing 



though. There is one subtle difference. The ARexx macros I am 
adding are intended to be pari ol the host application. They are 
being used as disk-resident commands rather than memory 
resident commands. See the difference? No. Well, I will explain it. 

By coding into Ihe host program, all the menu selections tor 
the commands and providing a way for the host program to call 
the ARexx macros, you make the macros an integral part of Ihe 
program and not simply an enhancement. In [his fashion, you 
create a standard set of macros that can easily be enhanced or 
embellished as the user sees tit. The main advantage I am looking 
for is the reduction in Ihe size of the host application. 

Ifthehost application is |ust ,i-,niallcoreof essential routines. 
while the remainder of the commands ,ue disk resident, the 
program can be quite small It would mostly be ihe small routines 
required to call Ihe ARexx macros into action. The ARexx macros 
and Ihe host .ipplication could then work together, passing the 
necessary information back and forth to each other to gel Ihe 
overall task accomplished. 

Using Ihe rexxapp.library presented a little challenge when 
I went to add an ARexx macro to work in this manner. I wanted 
to use Ihe ASyncRexxCmd or the SyncRexxCmd but you need a 
pointer to an ARexx message to pass to these commands. When 
the command is generated by a menu selection, there is no 
message pointer to pass to Ihese functions. I had to find another 
way to accomplish this. 

What I worked out was to add another message port to my 
program for asynchronous communications. I then added the 
signal for the new asynchronous message port to the variable I 
use in my main function to wait on for input events. I added a 
routine to handle activity at this message port. Finally, I added a 
small routine lo create an ARexx message and put an Argstring 
containing the name of Ihe command I wanted to execute in the 
ARG0 field of the message structure. I Ihensend this message to 
my own ARexx message port. That is a real roundabout way to 
execute an internal command. 

Dispatch Routine 

I also modified the dispatch routine to allow passing the 
arguments supplied to it by the rexxapp.library on to the functions 
it calls. You will notice thai 1 had to renameall Ihe function names 
in the RexxDala structure to accomplish this. Here is an example: 
|"open", (AFTR)&openfile) is now 

("open", (AFTR)&rexxopenfile|,. 
And ii\stead of calling the openfile function directly, it is now 
accomplished like this: 

BOOL rexxopenfilefstruct RexxMsg "msg, char "str, struct 
RexxData "data) 

) return(openfileO); I 

This change was necessary, because we will want some of the 
commands mourconunand-associalcd list to be able to execute 
macros. This is so because all the commands in our command 
associated lisl are called in exactly the same manner. So if one of 
these commands needs certain arguments passed to it, all the 
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commands have to receive those arguments. I*hey don'l have to 

use them, lust receive them. As you look tor all the changes In the 
program listings, you will notice that only one conunand uses the 
arguments passed to it The remainder of the commands are 
almost exactly me same as the one shown above 

[encourage you togooverthesourcecodecloselv to see how 
it has changed In hilly implement the ARexx interlace. The 
program can still be expanded with additional commands, but 
the interlace w.iuld still be the same 

Program Comments 

The Filer program is being used as .1 tool to show how you 
can add an ARexx interlace to your own program. It is nut very 
easy to use. I realize that in Its current configuration that you may 

not be tOO impressed with it. I am also riot ton impressed with it 
However, lam continuing to work With it to improve the interlace 

and functionality of the program. I have some ideas tor it that I 
hope to be able to share with you in future articles to show you 
how to use other aspects of the Amiga operating system. In the 

first part of this article, I did not give any instructions on how to 
use the Filer program. I apologize for that and include them now. 

Program Instructions 

The program runs in the background to be quickly available 

to access mim-database files. I originally envisioned these files as 
files I would create to act like small on-line indexes. As an 
example, I would like to be able to index all the articles I read in 
the various magazines I receive Man) times these arlu lesion tain 
items of interest to me now or that may interest me in the future. 
With this program, Icould easily searchmy database and rrndoul 
which article in which magazine I need to review However you 
could use it for any quick access items you want. 

lo activate it, press the Alt-Ctrl-t combination, and the 
program will activate itself. If the little Filer window is in the 
upper left-hand corner of your screen, then you don't need to 
press this key combination. You only need to activate the window 
to have access to its menu 

Clicking on the closewmdow gadget does only that It closes 

the window and puts the program to sleep but does not terminate 
the program. The Alt-Ctrl-f key combination brings it back to life 
The only way to terminate the program is through the menu Quit 
item. 

FheX'ew item in the Project menu allows you to create a new 

database file It brings up a window With lour gadgets m (he top 
row. 

The tirst two gadgets indicate the type Ol field vou are 
detining. The Key field type is used when searching the database 
and can hold more than one kej word as long as they are 
separated bv a Space The Raw field type holds raw information 
only and can be in any format you like. You can 011K selec t one of 
these gadgets 

The next gadget is the size gadget You specify the length of 

this field using this gadget Because the value entered here is 



never tested, be careful not to enter a length longer than one 
Screen line Press the return key after entering your value or the 
program will never learn about it. I capture only CADGETUP 
events Pressing the return key in a string gadget causes a 
GADGET"! 1 event to be sent 

I he 1,1st gadget is the name gadget. You specify the field 
name using this gadget 1 his is not the content ol the held, just its 
name Again, press the return key alter entering the name. 

Alter you have entered all three values, the field name, size, 
ami Ivpe will be printed below the gadgets. You can keep defining 
fields up to a maximum of 12 fields or click on the dosewindow 
gadget if you define less lh,m the maximum. 

The file definition you have just defined is only in memory 
and needs to K-savedtodisk if you want to be able to use it to hold 
data. To do this, you use the save menu item In the project menu. 
I his prompts you for a filename and then saves the record 
definition 

The open menu item in the project menu can beused toaccess 
a file previously saved The last opened file remains the current 
file for all other file activity until anew file is defined or another 
tile is opened 

I he add menu item in the edit menu, the new internal 
command, allows you to acid items to vour database file. The 
command opens it own window and presents the field names and 
string gadgets for each to get \ our input. Make .in entry in each 
held even if it is just a single character. Use the Add Another 
gadget in the lower right-hand corner of this window to add as 
mam additional records, is \ on desire (. lick on the closewindow 
gadget when you are done Again, press the return key in each 
string gadgel. 

Ihe last command is the view item in the edit menu, the 
ARexx macro added as a disk-based command, and is used to 
search the database file by kej held and display all matches. This 
mat id is fairly Straightforward and easy to understand. 

As I said earlier, this program still requires much work to 
become a full) functional program, and I intend to continue 
uorkingon it. If you see potential m this tvpeof utility program, 
I would appreciate vour input and help. You can contact me on 
(.1 rue using the e-mail address. I >. Black well 1 










/• Filer. h 

idau- file for the Filer progra-A. 
ccepiled to 

• ', IV*. -r<-jj ; : o ■ ; M 



T^IP ! 



.'* .... INCLUDES •/ 

•include <stdio.h- 

•include <fcntl.h> 

• include <ermo.h> 

■Include <string.h> 

•Include <atdlib.h> 

■Include "functions. n> 

■include <oxec/n**jory.h> 

■include <exec/execbase.h> 

•include «librane8/dosextens.h> 

■include «deviccn/;nput ,h> 

•include *devices/inputevent .h- 

• include -rexx/rewcto.h" 

•include <rexx/rxslib.h> 

•include <rexx/errors.h> 

•include <intuitlon/intuitionbase.h> 

'• .... DEFINES .... * 

•define DOS.REV 31 

•define GRAPHICS_REV 3) 

•define IKTUIT1CW_REV 33 

•define R£XX_REV OL 

■define REXXAPP_R£V OL 

•define BCOL 

■define FCOL 1 

•define RAW 1101 

•define KEY 110] 

•define SIZE 1103 

•define NAME 1104 

•define PROJECTHENU 

•define NEWFILE 

•define OPEN 

■define SAV! 

•define OUIT 3 

•define ED1THENU 1 

•define ADONEKRECORD 

•define VIEKRECORD 1 

•define ANOTHER 500 

Idefir.e NUHCMDS 11 

•define HAXFIELOS 12 

•define REXXAPPNAHE 'rexxapp. library* 

■define X0HIG1N 

•define YORIGIN 10 

•define XLENGTH SO 

•define YLEUGTM 10 

•define XDELTA 23S 

•define YDELTA 45 

•define FWINDCWIDCHP 

CXOSEWlWXWlKEWJPICKIACTlVEMlNTXWIJNACTIVEWlHnoW 

•define rrflNDOWFLAGS WINDCfcCLOSElACTIVATEINOCAREf 

•define NFWINDOWIDCMP CLOSEWIHOOHIGADCETUP 

•define NFWINDOWFLAGS 

WIKDOKLOSE I ACTIVATE I NOCA> * 

■define NRWINDOWIDCHP NFWINDOWIDCMP 

•define NRWINDOWFLAGS NFWINDOWFLAG5 

/• STRUCTURE DECLARATIONS • 

■truce CmdEntry ( 

char 'CindString: 

APTR CndHandler; 
If 



char • Ext en; 
APTR Func; 
struct RxoLlb "Hi 
APTR Error: 
APTR Result j 

■ 
truac User i 
Btruct CadEntry AsscListlNUMCKDSli 



I J 



.•ion ( 



.cbals 



■true 


Node defNode; 


i;byte 




UBYTE 




char Name|14]; 


char 


. |||r||| — r . 


char 


■ ■ 


char 


' 


."'.i 


1 " 


ULONG 


PexxSignal; 


ULONG 


ASyncSignal; 


ULONG 


IQtl 


struct 


window 'nywindow; 


struct 


List 'dp: 


char 


FlleNane[112)i 




lunt : 


BOOL 


sleeping; 


BOOL 


window., inactive; 


BOOL 


*U_done: 



■; 



■ 
i/Ol 

vol 

VOl 



M PROTOTYPES * / 

' : - v . 
tat (void): 
-ruct window •) i 
void DeleteArgBtringiSTRPTR) .- 
void clo8e_lnput_hondler(voitl) ; 

void Delfti-RrxxM-iglBtriri RexxHsg 'ti 

void FreeRexxPort f struct RexxData *tj 

void fleceiv - 

void releasegddi' ' ii>- • 

void eri 

* . 

void pt 



-nxxMsg •, struct RexxData 
struct PexxHsg 
LONG, LONG. STRPTR. struct BexxMsq 



■I ; Kt 



■cruet Resoant i 



RexxDaf , 

void Setup 

Rexxlte; ■ * 

BOOL closeit (void); 

BOOL rexxcloseit (struct RexxHsg •, char '. struct RexxData •): 

BOOL waxeuplvoid) r 

■ - ■" i ' Ui *. struct RexxDa' 

BOOL rexxactivete I struct RexxHsg *, char *, struct RexxOai 
BOOL newf ilelvoid); 

BCOL rexxnewfil«i(struct RexxHsg •, char », struct RexxData ■).• 
BOOL openf ile<void) ; 

■ txHsc *. char '. struct RexxData *); 

■■- - - xxMsg •, char •. struct RexxData •); 

■OOL rvaos-f- - xxMag *. char '. struct RexxData *); 

... . -j-, . ." . : •, char ", si rod 

BOO*, ito - struct RexxHsg *. char •, ai 

• 
BCOL rvotmtpt,.,!" ' - .-"(struct PexxMsg *. char ', struct 
RoxxDat 

BOOL viewrecoi 
BOOL roxxvi. -i ■ 
• . 

BOOL a • 
BOOL rexxaddne 



, struct RexxData 



ruct RexxHsg *> char *. struct RexxData 



struct KsgPort RexxPort; 



BOOL wiiterecordf struct Gadget *. atruct Window *): 
botl op*n_Lib*.lvoidlj 



22 



AG's TECH 



'SHORT) i 
BOOL oi".tt ;l-n.ir 

■ 

nexxHag •. 

■ 

■ 
*'\syncRexxQr>d(S7^ eocDaU •); 

Rexxlbg l struct Hex*." 

. 

■ 

■ 
■ 

i * ) : 
■ 
ULONG, 

■.-atePexxHsyiaO.al.dOl I 
1 , dOH 

■ 



ILIl8ttlltj&<§) IfW® 



Parae VAR tefTfMtf Name. index Type. tn<i- 
If Type. index -. Then Iterate f «v.. 

• 
keycou- 



1- ■ 1 1 



Bid 



1 



..'■■' • RaojUMt the record si. 

:i«n E.H PC 
Size ■ re^ i 

Exit " ■ 



I. ■ 



■ •- - ; value co a 

value. */ 

It - Open<'DetaFile' t Current_Ka»e. •R'l Then b 



/• '.^M-n an input channel *i 
-.(■KeyConaeJ 

■ 
■ . ■ : 
■ 



Then Exit 5 /* 
search otting. "' 






■ 






EC Willi 



■ 

1 » :.'.,.:...: 



i!r i Cur rent .Record /' 



j a temporary 



ler database 



■ 









I 

■ 



"rf to 



• The i 

/• parsed in the name ■ 
..■-. 1, I 

. Is - 1 
• ■ ■ 

*»x .position ».wp»ti 






to kayctnu 

r;iex 



■ 

Record. 

■ 

■ it per 

■ 

■ :nng 

■ 

. i» in 

■ ■ ' 



My* - l 



COrapor.' 

All 

■ 






end 
end 

Closel'D-v 



Show; 

• cord 
longo. ■ 

Do index) • to Tot«l_Fielda - 1 

■ 
End 



. . . 
la . 4) 






■ 



ID 
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reenter = (200 - height)/ 2 
Xcenter • (640 - length) /2 

bit_bucket • OpenCShowRecord' . *CC«: 'Xcenter'/ 'Yean 
• length V height '/Show Record') 

Do Index) ■ to Total_Fields 

bit_bucket ■ KnteLnf 'Sho-Recard'. Name.md. ■ 
Field. Index)) 
End 

bit_buckot > WriteChl 'ShowRecord*. 'Pr*» to con- 

ShowRecor i 

return 1 



Q,9@08ira@) TTBair©© 



l«i .c • 

/* Manx 5.0d soui ' 

/• cc -mc -md -sa -sb -sn -sp -sr -M Pilar. * 

/• In Fi lar.o Riot Intel '.■<-<•.■ :.lita •/ 

•include -Filer. h' 

f* .... C1j0r*I P . . 

Struct G (xBase 'GfxBase > MULL; 

struct ItoaLibrary 'DosBase = MILL; 

struct IntuitionBasc "Intuit lonHase = MILL: 

struct RexxBase 'RexxBase - WILL; /• rexxapp. library pointer 

"/ 

struct RxsLib 'RexxSyslMse i WILL: ■ • ARexx system library •/ 

UBYTE undobufflll.' f* Undo buffer for All string gadgets ■/ 

ULONG Event Signal; '* wake-up signal for event handle I ' 

struct Interrupt •syHandler.- 

atruct lOStdhcq 'myRequest; 

Struct Ksgpon "ay Port; 

struct Hag Port 'ASyncPort; 

struct Task 'myTaEk: /• pointer to Filer task sen 

•/ 

struct myGlobals 'Global; /* a structure to hold global 

variables */ 

extern char 'RexxErrKsg; '• error messag>- 

rexxapp. library "/ 



/* Comments on some lileds ol the myGlobals structure: 

(count 
record 

defliat 
comprise a record 

return^atr - pointer used to pans return strings t 

ARexx macros 

(ileptr 

■leeplfl j 
current 

window_inact ive 

all_dona 



a count of the definition structures in a 
linked list of field definitions that 



the active !...< nandlc 

These noxt three variables describe the 

daw throughout the 
: the program 



waitsigs 



- Signals that could wake-up the program 

struct RexxData myRP 

(NOLL). 

• ' ■ ■ 
(APTRi dispatch. 
NULL. 

(APTRi srroi 
(APTRI proccss_rtn, 
NULL. 
NULL. 

-new". 
lAPTRttrexxnewf !.■ 



( •open'. 
I 'save*. 

.'/ate*. 

( 'closoif. 



lAPTRtfctexxopen! 

■ 
tAPTfcifcroxxquitprog i. 
(APTRI trexx 

■ 

I APTRI *rexxr.upply ' 

■ 
■ 

I trcordBwC 
APTRIfcloxx: .;,.,■ . :e ) . 

■View, 
(APTT- . 

■ 
: i -• 



". ■ 

wont 

lude all thi 

■ 

pw' / " Ht" 

void main fvoidl 

' '■ 

Hon ayCodsji 

ULOH3 rtnsigs; 
struct RexxHsg ■■ 
struct IntuiMssaQsi 
static char PoitNem 



• 0, (APTRI > i 

■ am, \ 



, Requester 



utput I 



:•■-. 



if ( fOpen_Uba(l l 
goto main_- 



ARexx port name ' 
r.tf.i .itlnue 






IULLI I » 
port 



goto rvj 



CreatePortf -ASync*. (long) 0))| 

' a create an asynchronous massage f> 
goto stain.'- > 

I 

AllocHasi. ■ . 
WXF.CLEA}- 

• . - . i .' . ■ • . - i ■ • ; 

• 

put »< 'Not enough t memory for global variat 
goto main_exit; 

Clobal-^Bleepin; 

■ 

.Window • (*en_Hindow((SMORTI X 
I SHORT i 

(SHORT) X:-;. - - . FWINDOWFLACS. v 



■ 
■ 



Tory t 
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Global->eyKindow->Ui.< : • \*l the message pt 

then modify * 

HodlfylDCMPIClobal-JBvWindow. FWINDOWIDCHPI ; /• thi 
IDCHP flags • 

oxxBasei f tl Rexxfiase is not ti> Wary ib 

avallal ■:. 

< 

1! i : IGlobal-.RexxSign.t. 
■ Port uSTRPTRIPartName, fcmyRD] ii 



port .*; 



. 



in't open Rexx 



•) RexxBaBel; /• Can't 



span < pori 



library •/ 

I 



i ■- ■ l struct Rexxfiase *»0; <■ so close the 



•■•; two global a an- intended 



■ 

solely (or ■ 

EventSigti* . . • marl . . 

l.-\r. !';.-: • 

Global->PortSigr. i myPort->op_Sia> 

Global- >ASyncSigr.> ASyncPort->mp_SigBit > ; 

• Thla assignment wor' 
RexxSignal's valu 

Global- .waitsig. •.•ntSignal iClobal- 

>RexxStgnal 1 Global - >ASyncSignal 1 1 

instell_input_ha.ndlerimyPort) j /■ utart my input handler •/ 

SetMenuStrip<Global->eyw:indow. Honu : 

while 

I 

rtnsuu :- aigs); 

-■■•ntSignal) 
1 /• it the program is Bleeping or the window is 
inac ■ *l 

• recaivu an input event signal, then wake up or 
activate Chi ■ 

i'iow and process 'he user's request •) 
If (Global -.wind--- 

!l IGlobal->sleeping) 

if 1 1 tGlobal->sleeping) k*. rcnsigs L Globsl- 
*PortSlgnall 

• Process si -sasges that a:* 
window's messag.-' ■ 

/• port. • 

'« ImyMessage - (atruct IntulKesBage 
■>aeub0tmyPon ■ i 



i-- 



myClass - myM«B3age->Cla6S; 
myCode > myHes i 

FeplyKngi Isir . • Meaea*M> * 
■witch InyCi.i 

ease CLOSEwlHCCtt; 

CloM 

break i 
ca*e HENUPICKs 

Global->all_done = 

break: 
case ACTIVE* JKDOW; 

Global->sleeping * FALSE; 

GIobal->wlndow^ ; i : 

br.v 
Case INACTIVEWI.'ErjW: 

Global->Bleep. 



Clobal->window_inactWe ■ TRUE; 
break.- 
de(au . 

Global->error_atr • 'Unexpected 
class of Intuition Hessag< ' 

inf ormiGlobal - .myWindow) ; 



I 



I 



if IRexxBaae 44 Irtnsigs 4 Global ->HexxSignaln 
I /' I( Aflexx is available and we receive a signal 
■ -■ • 

'■ message port, call the rexxapp. library 
Diction •/ 

i <-ss all the outstanding ARexx messages. So 

Rece i veRexx I iryPOl ; 

.■.igo K Global->ASyncSignal> 
< 

while imyRexxMsg = .*Hsg •) 

GetMsglASyncPo!' 

if <ayRexxMsg->rtn_ArgstO| ) 

DeleteArgst r ing (myRexxMsg •trv_\t~ 
DeleteRexxHagfrnyRcxxMsg) ; 



close_lnput_hand.--i ; • ohut down input handler •/ 

naln_e> 

it (Global ->eyWindowl 

i! (Global -xnyKindow->MenuStripl 

ClcarKenuStrip(Global-»«vWindow)i 
Clobal->«yWindow->UserPort ■ HULL; 
CIoseWindowlGlobal-xnyWlndowl ; 
I 

if (ASyncPort) 

while (myRexxMsg - (struct RexxXsg •) GetNag (ASyncPort I t 

it (myRexxHsg->rm_ArgB|0|) 

DeleteArgst r i ng l PvPexxMsg - >rm_Args 10 J ) ; 
-o,xMsg(nyRexxMsgl: 



■Port); 



/fort I 

o all outstanding messages and delete the 
— s sage pott */ 

'■usage * Istruct IntuiMeasage •>GetHsg(myPortl I 
ReplyMagt (struct He&Bage • ImyHesaagel ; 
DeletePort (my Pott ) ; 

■perl 

Cloae(Globsl->filepcr); 

If (Global--: 

free* 

tf (Global- »RexxSignal I 
FreeRexxPort (tmyRD) ; 



-rn_str_lengthl; 



ret urn i 
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BOOL B . 



/• The (list thi 

operation */ 

■ 

Opvr 
I 

DUtB 1 * 

SWCCC- 
I 



the proyram-o 

1 

;raphics_I' 

loaded. *i: 



iDonBaBe : (struct DosLlbrary 
'lOpenLlbraryfck 
f 

i / could not be loaded."): 
sutceo 



I 

if ( ■ 

( 



litru. ■ « 



■ 



aucceoa • VHSSi 



the Oj- 

. -■ ■ . . . 

aj) AH.-— ' 

■ r(ace to work - 

... • 

OpenLlbrary (RIJOCAI'HiA.VE, KiJCXAl >. 

puts I 'Eexxapp. library •* 

■ ■ 



correct ly, 



■■ - 



on 



,• 



latruct Bxr-: iryiRXSNAME. 



' ("rexxsyBlib. libra:-. AJtexx port 

available. ■ 1 j 



Libs (void) 



irv ' ixBawi; 

.: |Dob8— < ; 

i-yiutruct Library *) DosBase) i 

■ 



- loiyil.- iry ■) RexxBasol ; 

ClooeLlbra; ■ 



width. 1 



•X itle.v 



SHORT heigh- . . I 
"creen **cml 
' NewVfindow KewWmdow; 

NewWir.cl - 



• • SHORT topadDja. 
LONG (lags, UBYTE 



NevWindow.TopEdge • topedga: 

1 



r it Cadger . >. - 

He*Window.ChocU4-> 
MewWindow. : i la; 

NevWindow. Screen * (or 

Newwindow.BitHap nitKap •) 0; 

NewWindow.H; 
■ 
tow.KaxWiJ' 

'..■■• 



Pj 



screen so make some 



cmi 

■ ■' 



lOpwiWindowifcrJewWindow) I t 



BOOL activatolvoldl 

•window_»r..i 

ActlvateMindow(Global->«yWlndowl: 
windovToFront (Global -MnyWindow) j 
Global->wlndow_lnactlv« ■ FALSE; 



■ 






:iucl RexxMag 



ar *nr r struct 



ictlvaiem; 



m 



The remaining code for Listing 
Three can be found on the AC'S 
TECH Disk along with all other files 
necessary for this program. 



Please write to: 

Dave Blackwell 

c/o AC'S TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 



\ 
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Iterated Function Systems 
For Amiga Computer Graphics 



by Laura M. Morrison 



Traditional graphics interprets objects In terms of geometric 
inures such as squares, circles, triangles, and polygons. 
Children are taught to draw by piling up spheres and cubes 
Many natural objects, however, do not lend themselves to this 
approach. They have the property of "self-similarity" and are 
more easily and realistically rendered in terms of smaller 
versions ol themselves. M.F. Bamsley and A.D. Sloan used 
iterated function systems (1FS) to encode images of natural 
objects in terms of smaller versions. By exploiting the property 
of self-similarity inherent to natural objects, they encode 
intricate natural images using only the coefficients Affme 
transformations. Although the number of transformations 
necessary to encode a picture ranges from a few to hundreds, 
IFS allow picture storage compression with ratios of the order 
of 10,000 to I (Reference 1) 

Besides their usefulness for image-storage compression. 
iterated function systems can serve the computer graphics 
artist. Even a computer artist who is unable to draw and 
knows no mathematics can use iterated function systems to 
render convincingly natural images of objects such as trees, 
plants, clouds, mountains and flowers. See Examples 1 and 2. 

Tne difficulty has been finding the Affme transformations 
which map the whole image into "tiles," or smaller versions, 
that cover the whole These transformations have the form: 

x2 = axl *byl + e 
y2 = cxl tdyl * f 

where (xl.yl) is a point on the whole and (x2. y2) is a point on 
the tile. They can rotate, skew, translate, or resize I lies, 
therefore, can be a versitile elements for rendering ol the 
whole. The most important characteristic of a graphically 
useful Affine transformation is that it maps the larger whole 
into itself. A tile must be completely inside the whole. Onv 



such transformation, if iteralively applied loa medium of 
infinite resolution, would map the whole into a tile, then tile 
into sub-tile, then sub-tile into sub-sub-tile, and so on — ad 
infinitum. If, however, many such transformations arc iterated 
randomly, the result is an intricate, natural-looking image or 
an intricate design (Illustration 2, and Examples 1, 2, and 3). 

Finding these transformations has required trial and error, 
and Serendipity for the personal computer graphics artist. A 
program that works for regular n-gons is available for the 
Amiga (Reference 2). Trial-and-error algorithms are available 
tor MS-DOS computers (References 3 and 4). 

The algorithm described here uses mouse-click input to 
define the transformations. Although this computer program is 
for the Amiga and relies on many Amiga features, the algo- 
rithm is portable. The section of coding that actually computes 
the coefficients is not Amiga specific. 

The program reads and displays a user-prepared sketch of 
the whole image showing indications of tile placement. See, for 
example. Illustration 1. The purpose of this sketch is to guide 
the user's mouse clicks. The user-artist clicks the left mouse 
button one tile at a time, point on the whole to analogous point 
on the tile, to tell the program how the whole image should be 
mapped into its many covering tiles. The program records the 
mouse click positions and provides feedback of what it thinks 
the user is doing. When three pairs of points have been 
collected, the program uses Cramer 's rule to solve six simulta- 
neous equations for the six coefficients, a, b, c, d, e, and f, of the 
transformation. A general purpose simultaneous equations 
solver is unnecessary since never more than three equations in 
three unknows need be solved at once. The six points input bv 
the user provide three equations in the unknowns a , b, and e: 

x2 = axl f byl f e 
and three equations in the unknowns c, d, and f: 
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Tqble One 



^ 



These ate the cc-v 

through -*.,..■> ■•;,.!■: .-■■ 

l.Bach to- car.:, end a. b. 

the translocation of points on the what* to paints on a 

Ixl.yll . . 

The ■econd fton I 
The last line cor.' . 

yoffset.paraMte: -^mputrd vi . 

plot on the Amiga screen. 



-0.04107 
0.37424 
0.01679 
O.30B4B 
-0.66426 
0.54116 
9<»« - 



-0.00026 

-o.oooai 

-0.14229 
0.16795 

-0.26067 
0.26868 



0.66614 

0.04610 
0.31581 

-0.05039 
0.00749 



0.18392 
0.45601 



i - ■ 



y2 = cxl t dyl • f 

IFS_coder rejects transformations with determinant ac-bd 
= 0. Other than that, does no error checking. It this were an 
engineering application, error analysis and control would be 
essential but for this graphics application checking is not e\ en 
useful. If the user- input- points do not correspond to mapping 
analogous points from the whole to a tile, then aberrant 
transformations can result but such transformations have not 
been excluded because they are easily spotted and deleted 
from the coefficient file and wild transformations can produce 
artistically pleasing abstractions at the computer artist's 
discretion, as well as possibly provide bizarre fission-type 
animations for galactic game programmers. Try Table 5 Fission 
coefficient file as input to IFS_decoder. 



■& 



Table Two 



The coefficients for Tree mage. See Fxar: 

input to IFS_decoder to produce the raw tiee lEUge. 



0.02498 


0.01159 










0.2183B 


-0,30785 


0.24203 








0.14046 


0.19801 


•0.36676 








0.20519 


-0.29528 


• • . 


■ 






0.11161 


0.16246 










-0.10304 


-0.27517 










0.10987 


-0.29JJ2 


. 








0.29200 


-0.16733 


■ : 








-0.207B6 


0.2B596 










0.01279 


-0.00024 










999.90005 


1.00C . 













IFS_coder writes a transformation's coefficients as one row 
to an ASCII file See, lor examples, Tables 1,2,"> and 4, coeffi- 
. ients tor a Weed, a Tree, an Orchid, and a Square. This file 
should DC ASCII because the user will want to edit it. adding 
transformations, removing erroneous transformations, or just 
"polishing" coefficients. 

I he user quits encoding whenever he wishes by clicking a 
"t loseVS indow" gadget hidden in the upper let! comer of the 
screen. The program will do numerous transformations or 
merely add one transformation to an old coefficient file With 
-onie extra coding it could remove the old "end of file" lines. 
As it is, the user must delete these before submitting the 
revised coefficient tile to lFS_decoder. 

The I FS_decoder 
program reads the 
coefficient file and 
iterates the transfor- 
mations randomly 
to produce a 
completed image 
(l Ming 2 

lFS_decoder). There 
is nothing necessary 
or magical about 
puking the next 
transformation 
randomly. It is 
merely the most 
practical way oi 
applying the 
transformations in all possible permutations of order. 

The literature suggests that each transformation be 
assigned a probability of being iterated commensurate with the 
area its tile covers. This would unnecessarily complicate the 
iteration code and doesn't change the final image. Should the 
user v\ ish to nu reasc ,i transformation's weight, he can 
duplicate or triplicate its row in the coefficient file and get the 
same erred 

I he program uses color to identify a tile's transformation. 
The register number of a tile's color in the final image corre- 
sponds (modulo 15) to the row number of its transformation in 
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the coefficient file. The SetRGB4(rastport,register,%red, 
%green,%blue) statements show the correlation between a 
color and its register. The computer artist will, of course, want 
to take the final image to a paint program and alter its colors. 

Iteration continues until the user is satisfied with the 
image's density and stops the iteration by clicking the 
CloseWindow gadget. The program automatically writes an 
image file. Or if the user is disatisfied with the image, he may 
abort the program by keying 'a' to quit without saving the 
image. 

Reading and writing image files is prehaps the most 
Amiga-idocyncratic part of the coding. Since the Amiga is 
multitasking, a program can run other programs from within 
itself. The 

" Execu te(< com mand _line>,0,0) " 

statements do that. They run Commodore- supplied public 
domain program "raw2ilbm" (not listed) to translate images 
between the raw bitmap image used by IKS_coder and 
IFS_decoder, and the IFF standard image used in Paint 
Programs. Notice, however, that the guide-sketch is not 
converted by IFS-coder. It will be used repeatedly and conver- 
sion takes too long. The guide-sketch must be available raw in 
the same directory as the program. The final raw image file is 




large so the program writes it to RAM;, converts it to a 
standard IFF picture file and then deletes it. This ability to run 
programs within programs makes prototyping an application 
faster and easier. To run the converter programs from the 
Amiga command line, type: 

ilbm2raw <imagefilename> 

raw2ilbm <imagefilename> <newILBMhlename> hi 4 

The number of transformations the IFS_decoder can 
iterate at one time needs to be unlimited. Notice that all the 
transformations must be iterated at one time since they interact 
with one another. It is not possible to, say, iterate half and then 
add an over image produced by the other half. Although a List, 
with dynamic dimensioning, to hold the transformation 
coefficients would allow unlimited transformations. Arrays, 
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even though of fined dimensions, arc better. Coding for 
iterations with Arrays is simplier and faster. Change 
MAXTRANS to change the Array dimensions to iterate more 
than 32 transformations. 

The IFS_coder program saves a list of the selected points 
to an ASCII file, called "<coefficent_filename>points". This file 
contains a list of the pairs of points selected by the user. There 
are six pairs of points for each transformation. The points from 
a walk-through of WeedTutor are given in Listing 5. This list 
can be ignored unless the user wishes to revise or polish the 
points. The new points can be input to the Points2Coefficients 
program to produce a revised coefficient file (Listing 3), 

The IFS_decoder program produces a list, called "points," 
of the first 50 points it generates. See, for example. Listing 6 
which gives the first 50 points of the Weed image shown in 
Illustration 2. This list is necessary in case the decoded points 
do not fall on the display screen. The Amiga display, with its 
origin in the upper left comer and its growth downwards. 
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values at the end of the coefficient file so the points wiU fall 
within the display screen. 

The trick to tiling is to make a separate transformation for 
each tile and pul each tile completely within the whole Kach 
tile requires three pairs of mouse clicks: a mouse click on the 
whole, then a mouse click on the analogous tile-point, three 
times. Illustration 1 describes what must be done. The more 
characteristic the points selected, the more faithfully the tile 
mirrors the whole. 

Indicators tell what the program thinks the user is doing, 
whether a click h.is defined a point on the whole ("From" 
point) or a point on the tile (" To" point). The number of pairs 
of points already clicked for the current tile is posted. (One 
transformation requires exactly three pairs of points.) The 
program also posts the number of transformations already 
completed. With very little practice, the user will ignore these 
indicators. 

A tutorial script walks the beginner through a tiling 
il isting4 for Tutor). Everything needed is in the tutorial 
directory. To run the tutorial, enter the Amiga CLI, change 
.1 1 rectories to the tutorial directory, and type: 

Execute Tutor 

Look for the resulting image in RAM: where the IFS_decoder 
program has put it. To see the final image type: 

View <ram:filename.pic> 

I op) the tile to disk tosave it. Illustration 2 shows how the 
resulting image should turn out. 
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differs from the standard mathematics tirst quadrant. The 
!FS_coder program automatically takes care of this for most 
transformations it defines. If not, the li~t shows where the 
points are going, and the user can adjust the scale and offset 
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No one covers the 

With the premiere monthly Amiga magazine. Amazing Computing , the technical depth of 
AC'S TECH. and the complete Amiga market insight of AC'S GUIDE, you have no better 
choice for keeping you up to date on the rapidly changing Amiga marketplace. 




Amazing Computing for the Commodore AMIGA 



Amazing Computing specializes in providing its readers with 
a broad knowledge of Amiga computing. With articles on the latest 
trade shows, the latest released products, indepth how-to's. plus 
informative programming and hardware features. AC maintains a 
standard of delivering only the very best. 

Whether through the controversial columns of Roomers or 
the always informative Bug Bytes, AC maintains the constant process 
of providing alternative views as well as help in making your Amiga 
do more for you. AC does more than any other Amiga publication 
to provide the latest information and the best news stories on what 
the Amiga will be doing next. When you want to know more and do 
more with your Amiga — AC is the one choice. 

Amazing Computing provides its readers the following: 

In-depth reviews and tutorials 

Informative columns 

Latest announcements as soon as they are released 

Worldwide Amiga Trade Show coverage 

Programming tips and tutorials 

Hardware projects 

The latest in non-commercial software 

All In informative, but in an easy to understand format 




AC'S TECH For The Commodore Amiga 

ACs TECH was created with the more experienced, or deter- 
mined. Amiga user in mind. It Is the perfect complement to Amazing 
Computing and ACs GUIDE. ACs TECH attempts to take the mystery out 
of intense programming and hardware development. The issues covered 
in AC'S TECHaie of interest to both the beginning programmer and the 
Amiga developer. 

AC'S TECH allows Amiga users to expand their knowledge and 
commit to larger projects while staying aware of the latest releases and 
other changes in the Amiga platform. This vital resource was the first disk- 
based Amiga technical resource available. It is, once again, the only such 
resource available and continues to improve with each issue. 
ACs TECH offers these great benefits: 

The only disk-based Amiga technical magazine 

Hardware projects 

Software tutorials 

Interesting and insightful techniques and programs 

Full listings on disk 

Amiga beginner and developer topics 



Amiga like Amazing 
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AC'S GUIDE To The Commodore Amiga 

AC'S GUIDE is recognized as the world's best authority on Amiga products 
and services. Amiga Dealers swear by this volume as their bible for Amiga infor- 
mation. With complete listings of every software product, hardware product, 
service, vendor, and even user groups, AC'S GUIDE is the one source for every- 
thing in the Amiga market. 

AC'S GUIDE also includes a directory of Freely Redistributable Software 
from the Fred Fish Collection and others. For Commodore executives, Amiga 
dealers, Amiga developers, and Amiga users everywhere, there is no better 
reference for the Commodore Amiga than ACs GUIDE to the Commodore 
Amiga. 

What do you get with AC s GUIDE? 

The best single resource for everything available in the Amiga market! 



Subscriber Benefits 

Every investment should contain some added value that makes your choice more interest- 
ing. An Amazing subscriber not only gets one of the best magazines available, but these addi- 
tional perks as well! 

Every Amazing publication has always been mailed in a protective cover or envelope. 

This means the end to torn covers or mutilated issues. We want your AC investment 

to always remain a solid value. 
Every AC Subscriber issue is mailed early. 

Every AC is mailed one week before the copies are shipped to the newsstands 

by the distributors. 
Toll-Free Access. 

An 800 number for toll-free (from the U.S. and Canada) assistance on your 

subscription. Amazing handles all subscription questions at our corporate offices. 

This means that your concerns concern us and we take care of your problems FAST! 
Money Back Guarantee. 

If you find your Amazing subscription is not everything you need for a better Amiga, 

contact us for a hassle-free refund for any unmailed issues. 



Now is your chance to enjoy the best savings ever available for these publications. 

This Amazing special is only available for a limited time. 

Use your MasterCard or Visa and call toll-free in the U.S. and Canada: 

1-800-345-3360 

HURRY! 

Due to the tremendous response received so far, The 
AMAZING SPECIAL deadline has been extended! 
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Listing Two 



■ 

• .ude *stdio.h* 

* vpes .h* 

1 

■include •cxec'menory.h" 
•include " ias.h" 

••• "".':■ 

1 : os.h* 

■include 'graphics gfxbaiu-.h* 

■ .-..:■ * ;:-iphjcfl/view.h* 

1 • " kntuii ;oji ,h* 

■in .ntuttlonbase.h* 

■ . 



• 


1 


' 


'.■:; 


HEIGHT 




i* Arbitrary -- 





* 
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I; 

extern struct 
■t ruct 

: its 

system 

requires 
messages wo 



■ . - 
■ 



,nj,. 



4 111 ICXI . ". -'1 



ned as well as • sen 



double bIHw 

IMAXTFANSJ; 
■ ■ 
double e[HAXTKANSi; 
double fHWCTFANS): 
doubl i 
. 

I 

■ ■ 

in' 

■ 
USMORT codej 

SHORT • 

.... 

,! 

float 

■ 

* 

integer. •/ 

. ttionBase *) 
Op.- ■ intuit ion. I ibrai . ■ 

NULL) 
I printf (-Couldn't open Eotuil 
goto abor' i 

GfxR-t - rRase 

■ • ■ ■ 
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goto aborted: J 

printfl*\n\n 1FS_DECOOEJ* Program Copyright 1991 \n*); 
pnntfi- by Laura H. Morrison \n")i 

print! I" BO North Moore Streot. Apt 4J\n'l; 

pnntfl* New York. N. t. 10013 Sn'l; 

pnntll" Telephone; 212-349-1818 \n'>; 

if large < 2 I 

1 print: <• Need coefficient filename on the command 
line. \n*l : 

goto aborted; I 

if ( argc < 3 I 
I 

print f (" Need output image filename on command line. 



\n')t 



pnntfi' Hone given so using a default name. \n'l; 



it If pp. fopen(argv(ll.*r'>) „ will) 

I print f ('Trouble opening the coefficient file.Sn'); 

goto aborted; 
) 
l-0j 
raadmoraij 

fncanf ipp. ■ If If If if If || 

•.talil.tblil.icIil.tdlil.ielU.fcfUii; 
ifl all) < 996.0 I 

I 

L..I 

lf( 1 > (KAXTRAHS-1> I 

print! I 'Too many tranaformat ions for allotted 
storage. \n't; 

goto aborted; 



l 
goto readmore; 



ntranr. 
(scant (pp. ■ If Id it Id 
\n*,lxscele,lxotfset,fcyscale,&yof !aet I ; 
fclose(pp); 

bitm > (struct BltMap 'iAllocHem(slxeo! (struct 
BltHapl.HEKF_CHIPI; 

it (bitPi-'NULL) 

( print! (-Couldn't allocate memory for bmap structure. 
\n*|; 

goto aborted: ) 
InUBUKaplbitm, DEPTH. WI DTH, HEIGHT1 ; 
planesue • (LOWS) IWIDTH/B> 'HEIGHT; 
for ti.O: 1 < DEPTH: !••) 

( bltm->Plajies|l|*(PLANEPTR)AllocRaster(HIDTH.HEICHTl; 
r>nm->Planes[il * = NULL) 
( print! ('bitmap planes were null\n'l; 
goto aborted; ) 
81tClear(bitm->Planes|il.planesize. . 
scr ■ tstruct Screen ')OpenScreen(tnewscr) ; 
i! (scr>>HULLl 

I prlntfCscr was null\n*l: 
goto aborted; ) 
nw, Screen = scr; 
nw. BitMap ■ bitm; 
w ■ OpenWlndow(tnw); 

it (W..KULL) goto aborted; 
rp ■ W->RPc: 

vp r fcw->WScrcen->ViewPort: 
/• Tiles are plotted different colors according to the 

transformations that define then, (modulo 1%) The SetRGB4t) 

statements tell which register a color is in. 

SetRGB4 (viewport. register number. Irod . Igreen. Iblue I •/ 

SetRGB4(vp.0.0.0.O)j 
SetRCB4(vp.l.lS.0,0); 
SetRGB4(vp,2.Q.0.1S); 
Set BCB4(vp.3. 0.15,0); 



■ 



SetRC84<vp.7.5.9.11); 
SetRGB4 <vp, 6. 8. 4. 6 1 ; 
SeLRGB4<vp,9. 9.2,0) ; 
SetflGB4(vp,10.Q.4.8)t 
Set RGB4 (vp. 1 1 . 0. 9. II ; 
Set RCB4(vp. 12.8.0. 2); 
SetRCB4(vp.ll.3.S,10); 
SetRGB4(vp,14,3.12.7)i 
SetHCB4tvp.l5.13.S.B>: 

SetRaat (rp.Ol ; 

yl ■ 0; 

count «0; 
/• <^>en a tile called 'points' to contain the first fifty 
points 

generated by the iteration. In case no image appears on the 

screen check these points to see where they are going. 

Adjust scale and offset parameters so points plot on the 
display."/ 

tp ■ fopeni*ram:points*, vi : 
for 

i whlle(( mess-(struct IntulKesaage ')GetMsg(w->Userr- ■ 

NULL) 

class » mess->Cleas; 
code ■ meBS->Code; 
x ■ mess->MouEeX; 
y • me*s->MouseY; 
ReplyHflgtmess) ; 

'• The program continues to plot points until stopped. 
When the image has a satisfactory density click the 
upper left corner where the CloseWindow gadget Is hidden. 
Closing takes a long time because the program writes a raw 
file then converts it to an 1LBH (lie. It works in ram 
rather than to disk because the raw file can be quite large. 
Copy the linage file to disk to save ;' 

it (class « CLOSeWIKDOU) goto finish; 
'* Key 'a' to abort the program without saving the image. •/ 

if I (class" VANILLAKEYIab(code--'a') t goto 
aborted: 

) 
'* By processing trans format ions randomly the program 
eventually gets all sequences of transformations and 
thereby all the points. There is nothing magical or 
or necessary about random selection. It is just the 
easiest way to exhaust the possibilities. "/ 
' randtl I ntrans: 
." Given the last point (xl.yl) calculate and plot the next 
point(x2,y.: - 

x2 . alrl'xl . b[r)'yl . e[r]i 
y2 « clrj'xl . d|r)'yl . f[r); 
xl * x2j 
y2; 
/• Calculate in double floating point, plot in integers ■/ 
nextx ■ (LCHGI (xscale*x2 • xottset): 
noxty * (LCNGHyscale*y2 • yoffaet); 
cc • (r I 14) • Lj 
SetAPen(rp.cc) ; 

■ Pixel (rp.nextx.nextyl ; 
/• Save the first fify points.'/ 
count • • ; 
if (count < SO) 

fprintfitp. ' Id lid %ld \n',r. nextx.nextyl : 



) 
finish: 



if targe < 1) 

( ttrcpy l filename. 'ramiout'): 

st rca t 1 f i 1 ename . argv ( 1 1 t j 
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•1m 

■ 
■tr< ■ 

. . .-. ..... . 

BCPT 



■• 



■ 
■ Planes,' i) .plane 

bCMpfO) I 

■ 



■ : 



" 



■«• 1 1 

■ . 
■ 
succwa • — 

■ 



pnt 






lb 



■ 
■ 

: ■ ■ 
■ 



Mop I I : 
it IGfxBas*) 






Listing Three 



tft.C 

■ 



■ ■ 

■ .: 

•include 'vxvc/inmroty.n' 

•lnclud ■ .-s/dos.h* 

loMXEara.h* 

I* 'graphics gtx.h* 



■ . ido 'orapJiic- -v:i-w.h." 

Dfl.h" 





■ ■ 

t2y|4|i 

■ 

■ 

LCWC 

stru ' .agw *miii 

:l«Hj 
-T code; 
SHOHT 

I, xr«ta].( 

t&Oj 

*"P. *Op; 

■ 

■-.met Intuit lonBao* 
ry" , 0) i 
i 

:on Wbrary\n'): 
gotc 

■ ■ 'flaw 

V.Ot; 

. c« library 
goto finish; ) 

'sage: Neod naves ol input points fil* and 
■ 

out) m«. \n*li 

goto t 



-jt tile \n'U 









■ l 
■ 

■ 
goi 



p.- Id Id td »d\n-.tpll.4pI2,tp21.ip22); 
l-(doubl«)plli 
kxibl«)pl2i 

■ 

p22i 



■ 

■ p.* »f \d \t 

goto flniahi 

■ 

■ i and 
.ems a, b, c. d. a. 

■ 
■ 



!tput la*. •; 



■ ; 
and f 
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al2 ' pclylOlj 
«22 = 1 

I 

•33 • 1j 
a 

hi • [■- 



deta««ll-|a22'a33-a. ■ 



■23*a3ll< 


■ 


■ . 




■••'-• 


0\n"»; 


' 


■ 


deta: 


• 


hi-(*i;v 




deta:. i .• ■ .■ , 


i-«2>- 


a31'thl* 






... . .. 


■ 




1 V" 1 




1 :■ ■ . 




e-doliT. 












. • 






- |*>a»t 


* 




deta22««r. • 


■: " • i33-«ll*h3l - 


* 




deta. 


■ i32t-a21*Ul 


•31*U12'h2 ■ ■ 




C«deta21/dcta; 




d*deta22/deta; 




f=deta23/deta.- 





fpt.ntltcp. -*.'■) . | LSI '. t 1. 01 

%.0(Vn\n*.«,b.C 

goto transformation: 

finish:; 

^p> fclosofopl; 

irccpt 

-. . . 

1 . Of \mn" .(ta.dn, <i- 

ipi ,i- : c| ' I 
■lat.xoff .yret.yoff ); 
tcloaelcpl ; 
l 

MuitionBaset Close'-ibiaryilr 

I /• end of Min •/ 



."-nts a, b. c, 
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128 














• 




.. 












lit 266 




■ 




324 H8 






■ 










38* 262 








1 


131 




• 


17} 166 


129 


)61 




250 199 








13 




■ 


■ 


2*0 79 










(29 


'.- 




129 


; J ■■ 


116 


•end* 


400 83 


999 


999 








999 

















Listing Six 



i.il «.0i 
lit %d 



Listing Four 



Horr tson. Id* 

Listing 4. 



Tutorial Script I 

1' ■ «— -J- .* ."cools 



Listing Five 



In can 



The f,< 






■ 



■ 








■ 


359 


J33 


161 


190 




•■■■. 




; ; 


: . 6 

















«■.: 






I'M 








E 









Listing 5. 

Points selected during wain through of Chi Mm . 
(with labels ar.d *n— ■• • 

These are the [■ rogram to 

equations 



Please write? to: 

Laura Morrisson 

c/o AC x TECH 

P.O. Box 2140 

Fall Rrwr. Mfl 02722-2140 
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Keyboard I/O 

from Amiga 

Windows 



by John Baez 

The Amiga has one of the most powerful and easy to use 
window interfaces on the market today. Il provides different 
types of objecls which fit almost any situation. However, there is 
one area in which the Amiga gadgets are far from sufficient. This 
is the area of keyboard I/O. 

Keyboard I/O is used to a certain degree in almost all 
applications. In some applications the Intuition string gadget 
suffices whereas in others it is clearly not enough. Anyone who 
has ever intended to write an application which requires substan- 
tial keyboard I/O understands what I'm saying. 

String gadgets do not permit the use of the up and down 
> ur-or keys to move from one gadget to tin- next I he\ dun": go 
from gadget to gadget as data is entered in each one. Thev don't 
allow things such as right justification or automatic edit checks 
when data is entered. Most of all they are very limited as far as the 
different types of data which can be entered. They offer no 
options at all as to where in memorv to store the data once it has 
been entered. 

These limitations make the use of string gadgets for key- 
board I/O very awkward and cumbersome for both the user and 
theapplication programmer. In this article we'll createa new type 
of window object called an lOField which provides a viable 
alternative for keyboard I/O. 

The features of lOField implemented in the code that accom- 
panies this article include the capability to enter data that 
accommodates short and long inkers, floats and doubles, char- 
acter strings composed of numeric digits and character strings 
made of any characters. You can also define your fields asdisplay 
only(OUTONLY), non-display data entry(INONLY),display and 
entry (OUTIN) or display after entry (INOUT). 

Fields can be displayed with a rectangular border (BOR- 
DERED), a double border (HILITE) or underlined (UNDER- 
LINE). You can use the text and background colors of your choice. 

I 'o-.it uming into a field can be controlled either by keyboard 
or mouse. The data resulting from keyboard I/O is stored at a 
predesignated location of your choice. 

I III III S!l.> OF ID 

In planning how we want an lOField to look and behave 
there are many possibilities. The code presented here is but a 
foundation on which a very sophisticated, yet easy to use, key- 
board I/O facility can be implemented. 




N 



Just like all other Intuition window objects, the lOField has 
a structure which is used tocrea tea linked list of lOFields with the 
desired attributes for the application at hand. A function is then 
provided which takes care of manipulating the linked list struc- 
ture and dealing with the I/O from the designated window. 
When keybaord I/O is ended or when an event not related to 
lOField is detected, the function returns the event to the caller. 

Listing 1 illustrates the lOField structure. To give you an idea 
of how lOField works, here's an explanation of each of the fields 
in the structure. 

The NextData field is just a pointer to the next lOField 
structure in the list or NULL if there are none. LeftEdgc and 
TopEdge identify the position of the top, left hand corner in the 
window of the rectangle in which a field is displayed. 

The Flags field is used to specify the attributes of an lOField. 
In this implementation those values are outlined in Table I. Later 
we'll see the effects of these attributes and how you can add 
additional ones. 

The FrontPen, BackPen and DrawModc fields indicate the 
color of the text, the background of the text and the dra wmode for 
using these fields. These drawmodes are the same as those used 
by other Intuition objects such as IntuiText. 

The Length field indicates the length of the field (incharacters) 
as it will appear in the window. The Data field is a pointer which 
points to the location in memory from which the field's value is 
read and to which it is written. This is usually a pointer to a field 
in a data structure. We'll see how those work later 

The EdFunc field points to a programmer-supplied edit 
routine which will be called whenever a value is entered or 
modified in the field. The last field is for programmer use and can 
point to any thing the programmer may wish to associate with the 
field The keyboard I/O routine ignores this field. 
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The internal functionality required to support the lOField 
structure has t> distinct functions. It displays the lOFields with 
their initial data values, reads window events, converts ra wkevs, 
performs a specific action based on the key pressed, navigates 
through fields either by mouse or keyboard and optionally calls 
an edit routine at the completion of each field's data entry. Let's 
take a closer look at these functions and their implementation 

The first function is to display the fields with their current 
values in the designated window. This is done by the 
displaylOData() function (Listing 3). First the field values are 
converted to character strings, by calling convfield(), then they 
are displayed as specified by the Flags field of the lOField 
structure. See Table I for a list of the flags and their meaning. 

Once the fields are displayed we wait for an IntuiMessage to 
come in for the designated window. When we get one we first 
determine if it is of interest to the lOField functionality. If it is, we 
proceed to process it. Otherwise we pass the IntuiMessage back 
to the calling application. These activities are performed by the 
getkeyO function (Listing 3). 

The messages intercepted are RAWKF.Y and 
MOUSEBUTTONS. Raw keys are converted to an unsigned 
longword representing the key hit . The "normal" keys are ass igned 
their ASCII code whereas function keys are returned as a pre- 
determined value. The value for some common keys are given in 
the header file "keys.h" shown in Listing 2. The conversion is 
performed by the function whichkey(). 



MOl Si HI IT C>\S are intercepted only if Iheyanainghtal 
a location within the rectangular display area of any of the 
lOFields. Otherwise they are returned to the calling application. 
The find_field() function (Listing 3) searches the lOField linked 
list with the mouse coordinates to see if they are within an 
lOField. 

The function performed on RAVVKEYs depends on the key 
pressed If the key has no meaning for lOField processing, it is 
passed back to thecallingapplication. The getkeyO and getDataO 
functions in I isling 3 'how the keys accepted in a case structure. 
The getkeyO function manages keys which work within the 
current field whereas getDataO handles keys which have meaning 
in the context of the entire window. 

When each field is completed, an optional, user supplied, 
edit function is called if present. This function can perform 
specialized edits on the field. An example, which can be used as 
a template, is presented in Listing 4. If this function returns a non 
zero value the screen "beeps" and the cursor doen't advance to 
the next field. The application will not let the user past this point 
until the edit function returns a zero (meaning the edit passed). 

The arguments passed to the edit function area pointer to the 
current Window, pointer to the current lOField and a pointer to 
the top of the lOField linked list. You can do just about anything 
within this function, even make a call to getDatal i 
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Flag name 

OUT1N 
INOUT 
OUTONLY 

INONLY 
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Table One 



lOField attributes 



function 



The field will display it's current value and then permit keyboard I/O to modify It. 

The field's initial value will not be dis-played. Keyboard I/O is permitted to place a value into the field. 

The field's current value will be displayed but cannot be modified. 

The field's value is not displayed at all. Keyboard I/O is permitted to modify it 



INTEGER The field value is stored in a 2 byte (short) integer. 

LONGJNT The field value is stored in a 4 byte (long) integer. 

FLOAT The field value is stored in a 4 byte floating point field. 

DOUBLE The field value is stored in an 8 byte floating point field. 

DIGITS The field value is stored as a nullterminated string of numeric digits. 

ANYCHAR The field value is stored as a null terminated string. 

BORDERED The field is displayed with a border forming a rectangle around the I/O area 

using the FrontPen color. 
HILITE The field is displayed with a double border forming a rectangle around the I/O area 

using the FrontPen color. 
UNDERLINE The field is displayed with an underline 

using lY\e FrontPen color. 
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Usting?usa sample program. The application is the outline 
of a simple mailing list winch shows the use of different lOHeld 
attributes. It illustrates how the lOField structure is initialized 
and how the getl)ata() function is used to process events in place 
ofthemoret\'picalWait((/GetMsg()combination.Italsoincludes 
a handy window)) function which permits you to open a window- 
without having to supply a NewWindow structure. 

Lines 81 through 103 define the lOFields and their support 
structure. Notice how the mailing list data is kept in it-- own, user 
defined, structure (called mailData) separate from the lOField 
structures. In this fashion the application doesn't have to deal 
with the lOFields for anything. This permits the programmer to 
concentrate more on the job at hand. 

Lines 143through I72illustratethemainloopof the function. 
Here you can see how the getDataf) function is used to get events 
from the window. The events are processed just as it they were 
received from a GetMsgf) function. Please note thai your 
application may receive MOUSEBUTTONS. RAWKEY and 
INACTIVEWINDOW events from IhegetDataf) function even it 
thev haven't been specified in \ our IDCMPFlags. Therefore von 
should always supply at least a stub for these IntuiMessage types. 

If you compile and link the code using the commands in 
Listing 6, you'll see how the fields work from the application 
point of view. You can play with theattributes to get a feel for how 
they work in different combinations. 



tMI V>4 IM. I III IOI M I II OBJM'T 

As I said before, the code presented for IhegetDataf) function 
is a foundation on which a very powerfull keyboard I/O facility 
can be built. For example, you can add a context-sensitive help 
facility which would display help text associated to each indi- 
vidual field whenever the HIT I'kev is pressed. You can add tield 
types such as date, time, currency, and others. You can add range 
checks and data sekvlion from a preset list of values Another nice 
feature to add would be edit masks which permit the field value 
to be displayed in a more legible format. I'm sure you could think 
up some more 

Facilities such as this coupled with other existing facilities 
make tor easy to write, professional -looking applications 

Usually adding a feature will mean either adding another 
flag or adding fields to the lOField structure. When implement- 
ing teatures, always try to keep in mind ease of set up and use. 
Adding leatures attached to kevs is usually justa matter of adding 
the key to the RAWKEY case statement in either the getkeyO or 
the getDataf) function. 

Well. I hope you find thecode useful. If I get enough requests, 
I'm willing to do a follow-up article with additional teatures In 
an upcoming article, I'll be providing you with a handluiof neat 
little functions which can be combined to produce impressive 
windows with very little programming effort. I'll show vouhow 
to create sophisticated edit functions. I'll be bundling them up 
and placing them into a shared library which you'll then be able 
to access Irom almost any Amiga supported language 
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Table Two 
Keyboard functions 



Key name 

Loft 

Right 

Up 

Down 

HOME APageup 

Forward lab 

Pagedown 

End 

Back space 

Delete 

Insert 

Return 

Escape 



function 



moves cursor left one character unless it is at the start of the field. 

Moves cursor right one character. At end of field advances to the start of the next field. 

Moves cursor to the start of the preceding field. 

Moves cursor to the start of the next field. 

Moves cursor to the start of the first field. 

Moves cursor to the start of the next field. 

Moves cursor to the start of the last field. 
Completes data entry and returns to the application. 

Deletes the character to the left of the cursor unless the cursor is at the start of the field 
Deletes the character at the cursor position, 
inserts a space for a character to be typed into. 
Advances to the next field 
Clears the field of its current value and places the cursor at the start of the field. 
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listing I : gcldala.c 



'lvldhr.(iaids) 

•dot* 



• . •. > on . h> 

■■oaactoa.h" 



' lOTield •fteitU, 

r - ' : 



cft*r witkISS], p*na. panh. draiaaadgj 



• 



■ 

In fta»i. 



.v«cs. non- 

■ 
■ 

- at ihim cod*. 



ltd ' p.vli-i 



■J* -«aya.n* 



. o en !■ 



tag* 

■ 



'• PV* 

■ latalist. 

.anally pamions itMll 

I daiaataii la 
■uppi 

■ 



a -na — "iri-'lgFtu: 

I '.MModa: 

n«ldal 

* laaoi PIEL0_MJOIPIED (lag and dlaplay 

tiald. 

■ da- >Plaga> It ia!da- 

tW.Vl K>> *PI>LDJ«X)iriFO( 
taldv 
■rlaVMOMfOOOi 

■ La-JifcCXTiNIOmMLYl 






>HfliPan>; 



flS)da->TopEilga>w->nPoil->TxBaielli 



!i»:da->ProntP<ani i 

■ !..-.:!■■ 



5atDtH.1iH->»roit . fielili- -Dl*-Mod»)i 



- -FPot! .-or*, f lolda- .Langtnl i 
t>. flout l'«r,- ! lelda- 



if UUilLtttl 



■ 



■ 






■ 
* 

■ 
■ 

■ ■ ■ -.■ 

j» * — aagti 

.-[Port I 
Modif/IOOUM-.f lagan 

■ 
•«ft_*lgl 






>n'i«-j'»"iH«i- 









OrawBardaMw- >PFort .tD.f kalda- 
>!*ritdga-2.fla)da->TOpSdga-2) j 

■ i-»t lontPeni 






■ 



>y_valu*a[( 
l|-ay_waluM|T|aw- 

tvBotdet (-->)• Poit.ab.fivlda- >L*fEEda«- 



if (UlNMHLIHEj 

Ualda- 

■Topldga-v-.nror- ,Tx>fe. i 

Hov»i«-»BPoit.n#lda- 

>L*r<.£dg*.iif 

DrMf(v>KFoit.f l*Ida->Uftl 

■PPMC-aTMUo) 

t iclils.f .elQn- -SeitData; 



-frui.panali 
SatBFanOf-.RPort.panBI i 



S»tDrNdiw->Hrflrt.<t«a'-«Qd«l 



raturnlUntlc) i 



-Idle.Iialdl 



if lalda->Langin*w- 
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Listing 2: mailer.*- 



■ 

■ 'j Intuit lot :-i-. 

■ 

■ 

■ 

; ' ■ ■ 

■ 





■ 

■ 



■ 

phor . 

v.. 

■ ■ ■ 

Incon- IT 





«-#_I0 



-. "i.WTIK 



■ 



I AIT* I" 

«0»_ 10 






- ■ . 



w, . 



phon»_[0 

io.iia.9o. 

■. 

BCtOUKD. I. J. JAM. 
I AIT' J'i'.o.fl.lll. 

..to 

* v.,. .■'.«! rBOWJEHKi. 



•Ail- 



■ 

It (intra .'.OVriHiAHVCHAHIBOWDOir 
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• Tint Contoi' 

■ 
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■lOei to picreaa RAWXTf *v»r.t»- 



• ■ , f*;_".Fi ■ 



■ 
' 
XatlM'. 10. 20.100. - 

■ ■ 






■ 



dupii 



-■', 



■ 



• 



loop. 

■ 






TTSO f< . 






Ml 



• lie 



■ 
rorjaii- 

tVMkj 



rhii 



■ do with it. vou P*y «iah to ■*» thlt * Mpui 

Mi rvM.'.i di 
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Cleanup and mit. 
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Listing I: k<-\ s.li 



Idaltr.- 
■define K_OlD 
IdVflnr 

IflBdll 



■ 

■ . 
■ 



I islini: 5: ml<l;ii;i.h 



* 






.•fl in any C 
■ ■■ 



* 
■ 
■ 

■ 

■ 

* 



■ MntKft 
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I raquaalvt i • ' 

- 
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GOTTA 
GETTA 
GUIDE! 



"N 



Looking for a specific product for 
your Amiga but you don't know who 
makes it? Want a complete listing of 
all the Fred Fish software available? 
Just looking for a handy reference 
guide that's packed with all the best 
Amiga software and hardware on the 
market today? 

If so, you need AC's GUIDE for the 
Commodore Amiga. Each GUIDE is 
filled with the latest up-to-date- 
information on products and services 
available for the Amiga. It lists public 
domain software, user's groups, 
vendors, and dealers. You won't find 
anything like it on the planet. And 
you can get it only from the people 
who bring you the best monthly 
resource for the Amiga, Amazing 
Computing. 

So to get all this wonderful 
information, call 1-800-345-3360 today 
and talk to a friendly Customer 
Service Representitive about getting 
your GUIDE. Or, stop by your local 
dealer and demand your copy of the 
latest AC's GUIDE for the 
Commodore Amiga. 

^ J 
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Pg. RS Number 


Ampex Systems 
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Central Coast Software 
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Delphi Noetic 
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J & C Computer Services 
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Memory Management 


62 
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Puzzle Factory 
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'Delphi Noetic asks that you contact them directly 



MOVING? 




SUBSCRIPTION PROBLEMS? 



Please don't forget to let us know. 
If you are having a problem with 
your subscription or if you are 
planning to move, please write to: 



Amazing Computing Subscription Questions 
PiM Publications, Inc. 

P.O. Box 869 
FallRiver, MA 02722 



Please remember, we cannot mail your 
magazine if we do not know where you are. 



eose allow four to six weeks for processing 
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ACs TECH Disk 

Volume 2, Number 2 



A few notes before you dive into the disk! 



You need a working knowledge of the AmigaDOS CU as roosi of ihe file*, on the 
AC- [ECH di«k jtc onlv accessible from the CU. 

In order to fit as much information as possible on the ACs TECH Disk, we archived 
many of the files, using the freely redistributable archive utility 'lharc" ( which is 
provided in the C: directory) lharc archive files have the filename extension .1/h. 

To unarchive a tilc/cc l:h. tvpc lharc xfoo 
For help with lharc. type ft 

Alio, ftlei with 'I- w be unurdmedfrom the Vt'orkBench by double clicking ihe icon, arui uipptxing a path. 




We prtde ourselves tn me quality of our print 
and magnetic media publications Howe/er . in 
rhe rtph'y unttkr-ly even! of a loutty or dam- 
ogea disk, please return the disk to ftM 
Pub* jejtio: <± ' >c. tor a free replacement 
Please return the disk to 

ACS JECH 

Dtsk Replacement 

P.O. Box 2140 

Fa* River MA02720-2140 



Be Sure to 
Make a 
Backup! 



CAUTION! 



Due lit lh> Kihiutal and opnimara.l "Mutt of KM 01 

ttr prey — om the AC"* TSCH Di»». *t >Jvnr ftc 
mdtfMiM>(»«Hin.nfnuUf >krauua(«>prfimraul 
profiun* ih« km li— li.<! diM m«M The «Mirr 
Ui*»l jj ill ihe quality and pcif lamiscr irf iht •.>(!» ■ r un 
dw AC i 1 1 1 It !•,.. ii ii.-imi »y 0m punbatcr PiM 
f»libi mkiih Inc. then dmnhmiav n then rtUitcn. •ill 
no br liabk (a •■• ihreci indmct. <* mnw^urnini 
J— ■!» nrmlnn| Iro in* uv i< miitmol iht nrfi»«< 
<*ilhr AC ■ TKIIIVt i flm if frrrntni m*j ma apply 
• alt fttjfnphKal area*) 



AMMMCk !■«•> 0*11* «*%.»■« tllc. and AlWWfW* on 

the AC'» TECH Didi art Inxh wdmnhuiabk. Ihe AC"l 
TECH ft tk rtwll wd ihe <uIImi>mi «( M-hodual fita aid 
ifcnfcum««mi)lwAf**TECHftU«topvri|«iCI990. 
199 1 br PiM PublKrtHB*. I*. . Md mi> mx br dMplKMad 
»an>*a> TntpunfuHihinorTiK^aitapdionukr 
•n •hWvcA*lup .t>p> of iht AC* TH7H Di*« 

UN Scotirfnel* .afelul *ten -oftini anh riardwat 
pujnu Chnk four »ort. (im ki niM *■> iimgt 
■ialt«»gfp f Atw. he a»aieiha<»*i»f ihtMpnijnii 

ma» \i-d Ihr »«n«*t*» ol tiu DMngln equipine* 

PiM IVMSt^aHw. b any of il'< ifCM*. ■> DO rrs-ntihk 
lia an> ilatnafct inonird »hile anemptiitf Ha* propx! 
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COPPER PROGRAMMING WITH 
HISOFT BASIC 

WOULD YOU BELIEVE AN 800-COLOR WORKBENCH? 

by Robert D'Aslo 



What Is the Copper? 

One of the hardware items which makes the Amiga such 
a graphics powerhouse is known as the graphics coprocessor or 
Copper. The Copper is a secondary processing unit residing in 
one of the Amiga's custom chips which relieves the main proces- 
sor (the 680x0) from certain tasks related to Amiga graphics 
rendering, thus providing a substantial boost in overall graphics 
display speed. It can control or modify the screen's display on a 
very low level, capable of bringing about changes on the screen at 
the speed of the monitor's scanning beam. Among other things, 
the Copper can change the contents of the color registers (as the 
PALETTE statement does) on each horizontal line of the display 
as it is scanned or "drawn" by the monitor. I his is how \ew I ek's 
Dynamic HiRes Mode and other similar display modes can take 
a hi-res screen with a depth of four which is normallv capable of 
only 16colors, and turn it intoa4096-color display- Each hon/nn- 
tal lineot the screencandisplay only 16 colors, but those l6colors 
are being redefined on <\ err scan line, thus making thousands of 
different colors possible on the entire screen. 

TheCopper is usually controlled entirely by the operat- 
ing system but the Amiga designers also provided means lor 
placing theCopper underapplication control, allowing program- 
mers the opportunity to directly take advantage of its power over 
the display. This can be done with BASIC but it requires an 
understanding of certain elements of the Amiga graphics display 
system. 

A Quick Overview 

Like most processors, the Copper is a device which can 
perform certain data operations when it is provided with coded 
instructions and the data itself to manipulate. The instructions a re 
referred to as the processor's instruction set and usually consist of 
"numbers" which the unit has been designed to recognize as 
commands to perform certain operations. As an example, the 
Motorola 68000 chip has an instruction set ot around 300 com- 
mands which it can recognize and perform. Fortunately, the 
Copper's instruction set is much smaller, comprising only three 
instructions. This may not seem like much at first, but some 
startling effects can be produced by programming the Copper, as 
can be seen from the listing at the end of this article a small 
program which can turn on and off an 800-color Workbench 
screen without adding a single bitplane to the display. Of course, 
manyothereffectsarepossiblewithCopper programming but I'll 



leave that matter up to you. 

A set of instructions for the Coppri is referred to as a 
Copper List. This list has an exact format which, if you are an 
Assembly Language programmer, can be "made from scratch" 
and given to the Copper for processing. The details for this 
method of building a Copper List can be found in the Amiga 
Hardware Reference Manual, published by Addison- Wesle\ . but 
there is a much easier way to create Copper I ists through the use 
ot system library routines and is described below. 

Once created, the memory address of the Copper List is 
"plugged into" a certain block of data maintained by the system 
known as a Viewport Structure and the system is asked to 
i ei on ti>;u re itself according to thiMiew Copper List. From then on 
the display is under control of the new Copper instructions 
provided by the programmer. 

The Viewport 

A ViewPort, in Amiga system parlance, is a re- Lingular 
section of the display with certain, definite restrictions I he entire 
display can be divided into twoor more Viewports but they must 
be above or below one another, never side by side. Viewl'orts 
must also never overlap, being separated by at least one horizon- 
tal line of pixels. Usually, when programming with BASIC, the 
displays created have only a single Viewport which occupies the 
entire monitor screen. It is possible, though, to create a display 
which is divided into two or more ViewPorts, each having 
different depths, resolutions, and color definitions. This isn't 
done very often, but it is possible on the Amiga. 

The system keeps track of each ViewPort (usually only 
one) with a block of data known as a Viewport Structure, which 
has an exact form. Since the term structure may be unfamiliar to 
you, I'll cover that ground first. A structure is simply a block of 
data residing in RAM and consisting of individual values which 
are usually one, two, or four bytes in length. Each of these values 
contained in the structure is called a field. The values contained 
in each field can change, but not their sequence within the 
structure. Structures a re very handy for storing a bunch of data of 
different types and. sim e the sequence of the data remains the 
same, the values contained in individual fields can be retrieved or 
changed by counting forward the necessary number of bytes 
from the beginning of the structure to the desired field. The 
position of a field in relation to the start of the structure is referred 
to as the field's offset. 
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Each line in (he definition below represents a single field 
of the ViewPort Structure and is identified with a name (or 
reference, its size in bytes, and a brief description of the value 
contained in that field. This structure is 40 bytes long. 

Viewport Structure: 

Next (4) - address of next ViewPort, if any 

ColorMap (4) - address of data describing colors used 

IJspIns 14) - address of Copper List, display info 

Sprlns (4) - address of Copper List, Sprite info 

Clrlns (4) - address of Copper List, Sprite info 

UCopList (4) - address of User Copper List 

DWidth (2) - width of the Viewport 

DHeight (2) - its height 

DxOffset (2) - x position of upper left corner 

DyOffset (2) - y position of upper left corner 

Modes (2) - display mode used 

reserved (2) - nothing yet 

Kaslnfo (4)-addressofanotherstructurecalled Raslnfo 

Only four of the above fields are relevant to the matter 
at hand, programming the Copper. These are the fields Dsplns 
(Display Instructions), Sprlns (Sprite Instructions), Clrlns (Color 
Instructions) and, most importantly, the UCopList field which is 
the address of the User Copper List. The user, in this case, is the 
programmer. All four of these fields contain pointers to (ad- 
dresses of) Copper Lists, but it is the User Copper List which 
comprises the customized Copper instructions needed to put the 
Copper under program control. The three other Copper Lists are 
maintained by the system. 

Creating the User Copper List 

Making our own Copper List is done with the help of a 
few system library routines from the exec and graphics libraries. 
This requires a familiarity with the use of the BASIC LIBRARY 
and DECLARE FUNCTION statements as well as bmap files. If 
you are unfamiliar with these subjects more information can be 
obtained from the AmigaBASIC manual, data on the Extras Disk, 
and numerous /Wi.j;m£C0mpuffn£articles.TocompiIe the listing 
provided, you must have copies of the files "intuition.bmap," 
"graphics.bmap," and "exec.bmap" in the LIBS directory of your 
system disk at compile time. 

First, a special structure must be created called a 
UCopList Structure. This is a very simple structure with a length 
of 12 bytes, containing three 4-byte values which are each ad- 
dresses of other, related structures. The details of these other 
structures don't concern us here, since we don't even need to 
provide the addresses. All we really need todo is set aside an area 
of 1 2 bytes in RAM for the UCopList Structure and let the library 
routines do the rest of the work. 

Allocating memory for use as structures can be done 
with the exec library routine AllocMem. This routine returns a 
long integer value (the address of the allocated memory) so 
requiresa DECLARE FUNCTION LIBRARY statement as shown 
near the top of the listing. The calling svntax of the function is: 

Address&=AllocMem& size&,opt& 



lhesi/e& parameter is the amount ol memor\ vou want in bvles 
and opt& is a value which represents one or more options 
available in the allocation o> the memory. Ine possible values are; 

-> no options, any memory 

1 -> nonrelocatable memory 

2 -> CHIP RAM, memory accessible by custom chips 

4 -> FAST RAM. memory inaccessible In custom chips 
65536 -> Clear the memory area upon allocation 

These options can be used singly or in combination by adding the 
appropriate values and using the sum as the opt& parameter 
when calling AllocMem. An example of the use of this function 
can be found within the AllocCopper sub in the listing, which 
allocates the 12 bytes needed for the UCopList Structure. When 
AllocMem executes, it returns the address of the allocated memory 
In the variable provided. Addressee in this case. It AllocMem fails 
in its allocation of the requested memory (usually because there 
is insufficient free memory available) it returns a value of zero. 
The program should always check to see that the returned value 
is not zero before proceeding, otherwise a system crash could 
result if the program tried to do something with a block of 
allocated memory that doesn't exist. 

Creating the User Copper List itself is done with the use 
of three graphics library routines. Calling these routines causes 
certain Copper instructions to be added to the list. 

The first of these routines is called CWait, meaning 
"Copper Wait." It is a command for the Copper do nothing until 
the monitor's video beam reaches a certain x/y coordinate. The 
routine is called like this: 

CWait* UCopList&,y%,x% 

The first parameter is the address of the User Copper List Struc- 
ture which was allocated earlier with AllocMem. We have this 
address because AllocMem returned it alter its execution. The 
next two parameters represent the screen coordinates for which 
theCopper is to wait, that is, the screen location which the video 
beam must reach before the Copper can go ahead with its next 
instruction. Notice that the y coordinate comes first, the reverse 
of the usual. Calling this routine will add an instruction to the 
User Copper List for the Copper to wait for the specified screen 
location to be reached by the video beam. 

The next Copper routine is called CMove. It places a 
command in the Copper List telling the Copper to write a speci- 
fied 16-bit integer value to a particular location in memory. It is 
similar to the POKEW command in BASIC. The memory location 
written to can be anywhere except the lowest 16 or 32 bytes 
(depending on the use or non-use of an option, which is beyond 
the scope of this article). The CMove routine is called like this: 

CMoveit UCopList&,register&. value"" 

The first parameter is the same as lor CWait, the address of the 
Copper List Structure. The register^ variable is the memory 
address when? the value is to be written, and value%isthe 16-bit 
value to be written to that location 

Why use the Copper just to POKE W values in to memory? 
The intended destination for these values is not just any memory 
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location; it is a special area of RAM known as the hardware 
registers. This is a /one of memory used by the custom chips and 
parts of the operating system to store special values related to the 
current operating state of the machine. Of particular interest are 
the color registers, a Mbyte strip of memory which holds the 
current color data for the Amiga's 32 basic colors. Bach color is 
represented by a 2-byte value which gives the red. green, and blue 
content of the displayed hue. These values range from zero to 
4095 or, in hex, &H000 to &HFFF. It's easier to use a three-digit 
hexadecimal notation for these colors because this illustrate-- tin* 
actual color being represented. Each of the three hex digits 
represents the red, green and blue content in that order. For 
example, the value &l 1408 would mean 4/ IS red, it 1 S green, and 
8/15 blue. 

When calling the CMove routine to change color regis- 
ters the values to use for the register^ parameter are (he even 
values from 384 to 446. These are the memory locations for the 
color registers. Color register zero (background) would he 384, 
register one would be 386, reg- 
islei two is VSM. .md mi t.n to 
color register 31 which is 446. 
By the way, these are not abso- 
lute addresses; they represent 
offsets from theabsoluie.ukhi 58 
&HDFF000. 

There is a third Cop- 
per List routine called CBump. 
This is used after each call to 
CWaitorCMove to indicate that 
the next Copper instruction is to 
be added to the list after the 
previous one. It's like pressing 
the return key after entering ,i 
line of BASIC code. If not used, 
then each instruction would be 
written on top of the last. To 
make things simpler in the list 
ing, one places the CWait and 
CMove calls in subprograms 
called CopperWait and 
CopperMove, each of whichalso 

contains a call to CBump. This s.nvsa lot of typing. The "waits" 
and "moves" can then be implemented by calling the subs like 
this: 

CopperWait y%pc% 
CopperMove register&,value% 

The address of the User Copper List is declared as a SHARED 
variable in both subs so it does not have to be included as a 
parameter each time the subs .ire called 

By now you should be getting the idea of how Copper 
programming is done. Using the CWait and CMove routines 
within the CopperWait and CopperMove subprograms, we can 
provide instructions for the Copper to change color registers .it 
.inv desired screen location. If, for example, we wanted the 
background color of the top horizontal scan line to be black and 
the background color of the next line down to be white we would 
code 



Like most processors, the 

Copper is a device which 

can perform certain data 

operations when it is 

provided with coded 

instructions and the data 

itself to manipulate. 



'wait for upper left corner of screen 

CopperWait 0,0 

change COLOR to black 

CopperMove 384 AH000 

'wail lor next line down 

CopperWait 1,0 

'now change COLOR to white 

CopperMove 384,&HFFF 

Actually, the above code would make the background 
color of the top line black and it would be white on all the 
remaining lines unless we added further instructions to change it 
to something else after the second scan line. Notice that, in the 
second call to CopperWait, the y coordinate comes before the x 
coordinate 

It's important to note thai in the above example we are 
not simply drawing lines of different colors onto the background 

of the screen. We are redefining 
die background color register 
for that line. If you can imagine 
being able to specify PALETTE 
Statements for even' horizontal 
line on the screen's display, 
you'd have the idea. 

Since we can change the 
color registers on ever)' hori- 
zontal scan line, a Copper List 
could require a lot of instruc- 
tions. Much typing can be saved 
by using FOR/NEXT loops for 
this purpose as is done in the 
"Main_2:" section of the listing. 



There Is CMore 

There are two other subs in 
the listing: AllocCopper and 
InitCopper. The AllocCopper 
subprogram allocates the 12 
In tes needed for the UCopList 
Structure using the exec 
AllocMem function as described above. The address of this 
allocated memory is returned in the variable UCopList& which is 
SHARED by all the other subs. It also contains a mysterious 
POKEL statement which is explained a little later. 

The InitCopper subprogram does three things. First it 
calls the CopperWait sub like this: 

CopperWait 10000,256 

What is this? How can the Copper wait for a screen position with 
these coordinates? It can't— well, it can wait but it better not hold 
its breath because the video beam will never reach the 10,000th 
horizontal line as it doesn't exist on the Amiga, not yet anyway. 
Using this wait instruction is simply the normal programming 
method for ending the Copper List instructions. It closes the 
instruction list 

The next line in the InitCopper sub places the address of 
the Lser Copper List in the correct field of the ViewPort Structure. 
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This is the UCopList Held which is 20 bytes trom the top ol the 
structure. The address of the ViewPort Structure was obtained 
earlier and placed in the variable VP& in the "Get 1'otnters:" 
portion of thelisting. This is accomplished with a routine trom the 
intuition library called View Port Address. View Port Add re** is a 
function which returns a long integer value so it also requires B 
DECLARE FUNCTION LIBRARY statement. This routine needs 
only one parameter; the address of an existing Window Structure. 
As you may have guessed or already know, a Window Structure 
is a structure for defining an Intuition window, but more on this 
later, too. 

The last line of the InitCopper subprogram calls an 
intuition library routine called RethinkDisplay. This routine re- 
quires no parameters; just call it by name. The address of a User 
Copper List has been provided in the View-Port Structure and 
RethinkDisplay will see it and incorporate its instructions into the 
screen's display. 



The Tricky Stuff 

What we have here isa 
noninteractive, toggling pro- 
gram. Run it once and it does 
something to the Workbench 
display. Run it again and it un- 
does what it did the last time it 
ran, returning the display to 
normal. The problem is: How 
does it know when to "do" or 
"undo"? A further problem is: 
When it "does," it causes 
memory to be allocated which 
must be freed up when it later 
"undoes"; otherwise, it will eat 
up memory every time it runs, a 
rather annoying attribute for a 
program. So, when il "undoes" 
how will it find the memory 
that was allocated the last time 
it ran so it can then be freed up? 

First let's look at how 
much allocated memory is in- 



A ViewPort, in Amiga system 

parlance, is a rectangular 

section of the display with 

certain, definite restrictions. 

Usually when programming 

in BASIC, the displays 

created have only a 

ViewPort. 



for the note It the note is there, it "undoes" the display; other- 
wise, >* "does" it. 

I'll have to back up a bil toexplainwh.it I mean. All the 
graphic objects which are pari ol the Amiga operating system 

have structures which define them Windows, menus, gadgets, 
screens ,ind soon all have special structures in KAM .isso, i.iU'd 
with them. The Screen Structure is rather large, over 300 bytes in 
length, and contains a great deal of information, including entire 
substructures. There is one particular field in the Screen Structure 
called the UserData field which can help us with this problem. 
This held is four bytes long and is located 338 bytes from the top 
of the Screen Structure. It's there for the programmer to do with 
as hechwses Any value can be placed there and thesvstem will 
maintain it. This is where the program leaves its "note" This is in 
the form of an arbitrarily selected value, &HCCCC, which is 
placed in the UserData field of the Workbench Screen Structure 
bv the AllocCopper subprogram in the listing whenever the 
program creates the User Copper List. The UserData field is 

cleared to zero whenever the 
program "undoes" the display. 
When the program starts up, it 
looks in this held to see if the 
code value is there From that 
point it branches to the appro- 
priate operation. 

I lure is one little wrinkle to 
i his How do we find the Work- 
bench Screen Structure? Intu- 
ition comes lo the rescue here in 
the form of an intuition library 
function aptly called 
GetScreenData. This is how the 
tuixtnm is used: 



single 



vol ved. We used the AllocMem routine toallocate 12 bvtes tor the 
UCopList structure. That'snot so bad. I suppose wecould just call 
it negligible and forget about it. Even if the program were run 100 
tune-, only 12 K of memory would be lost. Unfortunately there 
is more to it than this. The User Copper List itself take- up 
memory. Each instruction in the li--[ uses four bytes. The FOR/ 
NEXT loop in the "Main_2:" section of the listing goes around 200 
times, adding five instructions to the User Copper List each time. 
That's 1,000 instructions times (our bvtes or 4 Kol memory just for 
the Copper List. There are also structures initialized by the 
system that come into play. The bottom line is, it just wouldn't do 
to forget about freeing up that much memory. 

Let's attack the first problem: How does the program 
know to "do" or "undo" the display? This one is pretty simple, 
really. The program leaves a "note" tacked to the Workbench 
screen whenever it "does" the display and removes it whene\ ei 
it "undoes" thedisplay. Each time the program starts, it hrst looks 



success 4 GerScreenData& 
buf& .si/e". ,rype% ( screen& 

The success^ variable will be 
assigned one of two possible 
values when the function ex- 
ecutes. It will be false (zero) if 
the function tailed or true (-1) if it succeeded. The success variable 
can be tested after calling the function to see what happened and 
the program can branch as appropriate. In the listing provided 
the program aborts if the function fails. The buf& parameter is the 
address of a bufrer to hold the data that GetScreenData provides. 
You can use an array for this purpose and pass the value 
VARPTR(array(0))forthebuf&parameter Si/e , isthesi/eofthe 
buffer in bvtes I he type", parameter is one of two values. If 
you're after the Workbench screen use a value of one (&HI>, 
Otherwise use a value of fifteen (&HF). The last parameter is 
ignored by the GetScreenData it you have requested data on the 
Workbench screen so it can be zero in this case (as it is in the 
listing); otherwise, it is the address of the Screen Structure being 
sought. The function will read all or part of the Screen Structure 
into the buffer you haveprovided. the amount read depending on 
the si/e".. parameter. GetScreenData also requires a DECLARE 
iL\v I ION statement 
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Before calling (..etS. rccnData. a buffet i> created by 
Hi Minj; long integei .Ht.n ol Sufficient length .ind its address i*. 
passed .is given above. I ; or our purpose we need only the lirsl 
eight bytes ot the Screen Structure, as bytes S through 8 contain 
the dabi we're after the address »>t the Workbench screen's 

window. This is, of course, the address ot another structure, a 
Window Structure Once we have this we can tind the address ot 
the Viewl'ort Structure (to which we will later attach the User 
Copper List) by calling the Viewl'ortAddress function described 
above. (The Viewl'ort Address function requires the address ol a 
U nutow Structure todoits job.) While we' re at it, wecanalso tmd 
Iheaddr»>ssoftlK'WorktH.'ncliNrc«nStruLlureitsehbvri:i ; KI.jng 
at anoltset ol 46 bytes trom the top ot the Window Structure, as 
this is where that address is located. This allows us to locate the 
t -11 Data Meld ol the Screen Structure to See it il contains the 
note" or not. mi the program will know which wav logo. Allot 
this is done in the first lew lines ofthc "Cctl'oinlcrs:" portion of 
the listing. 

Dismantling the Display 

All ol the freeing up ol previously allocated memory is 
done with a graphics library routine called IreeYTortCopLists. 
I here are twoother, similar routines tn the graphics library called 
FreeCopList and FreeCprList. The difference has to do with the 
tact that there are different types of Copper Lists. According to all 
the system documentation I have seen, none of these routines is 
designed to free up the memory' specifically and only associated 
with a User Copper List. The safest bet seems to be the 
FreeVI'ortCopl.ists routine. Notice the "s" at the end of its name 
This routine deallocates the memory for all the Copper Lists 
contained in the Viewport Structure at once. It first looks at the 
lour fields in the Viewl'ort Structure which contain Copper I ist 
Pointers and works trom there, freeing up all the allocated 
memory associated with them The trouble is we don't want all 
the Copper I is ts dismantled, |Ust the User Copper List. We want 
to leave theCopper Lists associated with the normal Workbench 
display alone so that the original display is restored. To solve this 
problem, 1'vecome up with a little trick to fool FreeVPortCopLists 
into treeing uponly the UserCopperlasi and the trick works. The 
program lirst sa\ es the contents 01 the Viewport Structure fields 

v\ Inch contain the addn-sMsot me three other Copper Lists. (See 
the Dsplns, Sprlns and Clrlns fields in the definition of the 

View Port Structure above I Alter their addresses are saved, these 
ihree fields are then cleared to zero and HreeVPortCopI istS is 
called Seeing nothing in the first thai- Copper I 1st fields ol the 
ViewPorl Structure, the routine ignores them. Since the UCopList 
field is the only one containing an address, the User Copper List 
memory is Irivd Alter the routine finishes, the values previously 
held in the three other Copper List fields are returned and the 
original display is restored with a call to Intuition sKethinklJisplay 
routine. 

Compiling and Running 

I he listing was written for the HiSoft BASIC Profes- 
sional compiler version 1 .05. The compiled program, which is on 
the companion disk for this issue, was compiled to stand-alone 
form, so it can be moved around without fear of losing support 
files. The resulting hie si/e is .ibout 16K, including the linked 



I iiSill library 1 . If you are typing in the program and compiling it 
yourself, you may have to change the ver\ first lineof code to suit 
your hardware configuration. This line contains the "F" option 
instruction "FDF1:WB800" which outputs the executable to a (ik- 
on DPI:, which won't work if you don't have a DPI: mounted. 
Running the program is done either by double clicking its icon or 
by direct call via the CLI/Shell The resulting executable file, 
called WB800, is rather startling, an 800-colot Workbench screen! 
The more windows and icons on the screen, the more colors will 
he visible. Hach of the four Workbench colors is redetimd on each 
of the 200 horizontal scan lines, so moving an icon or window 
vertically causes its colors to change. Running the program again 
restores the original Workbench display. You can also see by the 
memory counter at the top ot tin- screen that all of the memory 
consumed by the customized display is released when the dis- 
play is restored, so the program can be run as main times as 
desired 

Copper Applications 

Normally you wouldn't have to worrv about Ireeingup 
the Copper List as is done in the Main_ I : part of the code because 
the system will do this when the screen is closed. This listing is a 
special application for an unusual situation: providing .1 I ser 
Copper List for the screen of a currently-running program. Work- 
bench Hie usual application would be tocreateacustomSCREKN 
and WINDOW, provide a User Copper List with some variation 
of the Main_2: section of the code and then close the screen upon 
exit from the program. Closing the screen will tree up the User 
Copper List. 

Copper programming is a great way ol providing addi- 
tionakolor toa display without gobbling upchip RAM by adding 
bitplanes (depth) to a screen. Multi-colored backgrounds, text, or 
graphic objects become easier to provide, especially with larger 
programs which already consume quite a bit of RAM due to the 
hefty files output by the compiler. Theoretically, a s, reen with 
only a single bitplane (depth of one) could display 400 different 
colors at once using this method! 

Feel free to experiment with the code. It's interesting to 
see the different effects possihlr 





All listings lor Copper Programming ran In- 
found on tin- AC-ITCII |>i-k 



Please write lo 

Bob D'Asto 

c/o AC's TECH 

P.O. Box 21 U) 

Fall River, MA 02722-2110 
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MenuScript 



Creating commercial-quality menus with this easy-to-use language 

by David Ossorio 



Introduction 

This is MenuScript. a small high-level language for 
designing text menus on the Amiga. MenuScript is both a 
language and an interpreter, easy to leam and easy to use. 
which lets you describe the appearance of your menu with 
simple ASCII scripts, using a minimum of effort. The 
interpreter displays your completed menu and writes its 
source code to the file of your choice in any of C, assembly 
language, or AmigaBASIC Just compile and link. What 
used to take days can now be done in minutes. 

Motivation 

MenuScript is unique among Intuition utilities. Its 
design was guided by two philosophies: a language for 
describing text menus should be simple and easy to use. 
but control over fine detail should not be sacrificed for such 
ease-of-use. More about the second point later, but first, 
what is meant exactly by ease-of-use? 

Suppose we want plain vanilla menus with no fuss. 
Then MenuScript should be smart enough to fill in the 
details in a way that makes the menus look good, even 
though we haven't specified anything but the actual text 
for the menus. In other words, MenuScript should have 
reasonable defaults which do not have to be continually 
reset after each use. 

This may seem obvious, but consider a commercial 
program like PowtrYJindows, which requires you to per- 
form a long sequence of clicks and typing reconstruct plain 
text menus, and even then the results are often not what 
you had in mind. TheGUI technique that works so well for 
designing gadgets and images is not necessarily the most 
efficient way to design a text menu. It would seem more 
natural to describe a text menu with actual text, usin^ .i 
language which hides the most tedious details of construct- 
ing the source code for that menu. 

As an example, here's how you would construct a 
simple menu in AmigaBASIC: 



KB4U 

MENU 
MHfll 



1,0, 'Project" 
1,1, 'New- 
l.J.-Open- 



This is certainly much more intuitive and simpler than 
the correspondingC code would be for the same menu. We 
havespecified only minimal information, and AmigaBASIC 
has done the rest. 

But there is a steep price we pay for this ease-of-use in 
AmigaBASIC, namely that we are able only to display the 
most general type of text menus. There are no provisions 
for specifying command key equivalents, whichare present 



in virtually all Amiga software. We can't even construct sub- 
menus in AmigaBASIC without reporting to calling the 
operating system routines, which defeats the whole pur- 
pose of using AmigaBASIC in the first place. Clearly this is 
an unacceptable compromise, and it brings us to the second 
design philosophy behind MenuScript. A language for 
designing text menus should allow you to create complex 
non-standard text menus. It should allow you to override 
any default values it uses and specify the exact appearance 
of the menu. In short, anything you could do if you wrote the 
source code yourself you should be able to do with that 
language. Obviously this is not a small requirement, but 
you will see that MenuScript comes pleasantly close to this 
ideal. 

How to Start It 

MenuScript iscalled from theclihv typing the following: 

ms [>redirection file] |-dplabc/| inputfile.menu 

MenuScript sends all of its output to stdio. It you don't 
want the output printed on the screen (which is usually the 
case), you must redirect it by typing '^redirection file". For 
example, "ms >dfl:MyMenu.h MyMenu menu" reads the 
file "MyMenu. menu" and sends the output to "MyMenu.h" 



Additionally, 
optional switches; 



MenuScript recognizes the following 



-d This tells MenuScript not to display your menu. By 
default MenuScript lets you see the completed menu before 
it writes out the source code. Using the '-d' switch overrides 
this. 

-p This tells MenuScript not to write the source code 
for the completed menu. Useful if you'reexperimentingand 
only want to see the menu. 

-I [letter el) This tells MenuScript not to display the 
line numbers when reading the input file. Normally when 
you run MenuScript you get a message like this: 



MenuScript 
Reading. . . 



Version x.x. 
Uine nuniberl 



where [line number] is the line of the input file that is 
currently being read. If you're really in a hum . you can 
speed things up slightly by turning off the [line number] 
display in this manner 

•z' If you use this switch, MenuScript prints a list ot its 
default settings and terminates. 

a This tells MenuScript to create .is>embler source 
code. 

-b This tells MenuScript tocreate AmigaBASIC source 
code. 
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II you don't specify otherwise, you get C source code; the -c 
switch is redundant. MenuScript can only output one type ol 
source COdeata time, so only oneofC, Assembler, or Amigal! ASIC 
may be specified. 

How To Use MenuScript 

Before we dive into a precise definition of MenuScript s\ n- 
tavlook at the following rile written in the MenuScript language: 



describes a relat 



.menu "Pi 

"New" key N 

"Open" key O 

■ Print" 

-subi -Draft" checkable check 



Notice thai MenuScript is compact without being cryptu. ~o 
you won't have to -.pond a lot of time learning its syntax. Also, 
each line of a MenuScript input file can be divided into tin- 
following simple elements: 



1 . Comments 

Any text following .1 ';' or '" is treated as a comment. 
%%< Comments end at the end of a line, and a completely blank line is 
++4 treated as a comment. 
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2. Commands 

In MenuScript, commands always start with a period (-)and 
are used to declare menus, items, and sub-items. There are also 
commands tochange default values used in determining how the 
menu will look. 

3. Parameters 

These are sometimes optional arguments which always to! 
low commands. They a I low you to give the MenuScript interpreter 
more specific information about the appearance of your menu. 

There are only a few things to keep in mind when writing a 
file in the MenuScript language. First, remember that MenuScript 
is a scripting language. Only one command is allowed per line, 
but that command can be placed anywhere on the line. Param- 
eters which follow a command must be on the same line as the 
command, and they can be separated by commas or spaces or 
both. Also, commands and parameters may be written in upper 
or lower case, or both. 

That's it. Now we take a detailed look at all of the commands 
and parameters which make up the MenuScript language. You'll 
find that MenuScript is rich enough to express just about any type 
of text menu you might want to use in your software application, 
and that even very complex menuscan be constructed in minutes. 



Commands 

Command MENU 

Format .MENU <name> [menu option)" 
Template .MENU "MenuName" OFF 

Purpose To begin a new menu. 

( [option]' means that zero or more options may follow this 
command.) 

The .MENU command sets the title bar of a menu. For 
example, for a "Project" menu, you would write: 

.menu ■ Project " 

Any .ITEM commands encountered after the .MENU com- 
mand would naturally belong to this menu. To start a new menu 
to the immediate right, simply repeat the .MENU command. 

Currently the only parameter which may be specified after 
the .MENU command is OFF, which will initially ghost all items 
and sub-items which belong to this menu. Using the OFF param- 
eter is equivalent to clearing the MENUENABLED flag of the 
Menu structure for this menu 



Command 1 1 1 M 

Format .ITEM <itemname> [item option)* 

Template .ITEM "ItemName" [CHECKABLE.CHECK, 

TOGGLE, OFF,BOX,COMP,NONE, 
SELECT <name>, EXCLUDE <item numberV 

END, 

KEY <command key>] 

Purpose To define a menu item. 




IttttfttltlilJtlltltlliltifttf ♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦* 

A* .AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.A.A.AA 



AAAA 



♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦ 

♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦* 



SetMenuStripfwindow, MyMenu) ; 

in your application program. 

If voudonoi ust the NAME command, MenuScript assigns 
b default name, MText', lo your menu, and in thai cist- the menu 
could he displavevl in your application bv writing: 



JTEM sets the text for an item belonging to the latest Ml \L 
Any sub-items (.SUB1) encountered between here and the next 
instance of .ITEM will belong to this item. So continuing our 
example from above, suppose that we wanted our "Project" 
menu to contain four items. We would then write; 



.menu 


"Project" 


.item 


-Open" 


. item 


"Save" 


.item 


- 


.item 


"Close" 



thi 



s is our project menu... 



(item options] are explained when we look at parameters. 



Command .SUBI 

Format .SUBI <name> litem option]* 

Template SUBI "Sub-item Name" 

[CHECKABLE,CHECK, 

TOGGLE, OFF,BOX,COMI\ 
NONE3ELECT <select name>, 
KEY <command key>, 
EXCLUDE <item numbers-' END| 

Purpose To define a sub-item. 

.SUBI set-- the text lor a sub-item belonging to the latest 
item. In our example, if we wanted the "Print" item to have two 
sub-items, we would write: 
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.menu 


"Project" 


.item 


■Open" 


.item 


"Save" 


.item 


"Print" 


. subi 


■NLO" 


.subi 


■Draft" 


. item 


"Quit" 



litem options) are identical to those for the ITEM commands 
and are explained when we look at parameters 



Command .NAME 

Format .NAME <name> 

Template .NAME "MyMenu" 

Purpose To specify the variable name of the pointer to your menu 

strip. 

In any program that uses menus, you must call the Intuition 
functions SetMenuStrip( ) and ClearMenuStripl ) to set and clear 
your menu strip. These functions require a pointer lo a Window 
structure and a pointer to a menu structure as input. When you 
use the .NAME command (i.e., -NAME "MyMenu"), MenuScript 
puts the following line in the menu source code: 



Vol LdDJ 



t Menu 
MyMen i 



■MyMenu ■ . . . / 

■ 



Create a global 



The variable 'MyMenu' points to your menu strip, so you can 
easily write: 



:;uStrip(window, MText ) ; 



Command .FONT 

Format .FONT <fontname> <height> 
Template: .FONT " you rfont. font" <height> 
Purpose I o construct a menu using a custom font. 

.FONT allows you to easily construct a menu using a custom 
font. MenuScript will attempt to open the font specified in 
"font name font" (the font can be disk-based), and if successfully 
opened will show vou your menu in that font. Placement of 
menus* Items and sub-items is alw.ivs calculated using the Width 
and height of the current font, so if you don't specif)' a font, 
MenuScript defaults to TOi'AZ_EIGHTY. Additionally, if this 
command is used, MenuScript will write out the Text A ttr structure 
ofyourfontandplacea pointer to it in the global variable 'MAttr 
The .FONT command may be used only once, but may occur 
anywhere in the file. 



Command CHECKIMAGE 

Format .CHECKIMAGE 

Template .CHECKIMAGE 

Purpose To define a custom checkmark image 

If you're bored with the old Intuition checkmark imager \ >>[ 
wan) a checkmark image that's consistent with the font vou're 
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using, then you can use the command asa crude way of construct- 
ing .i one-bitplane checkmark image I he .CHECKl MACE com- 
mand must be on a line by itself; subsequent lines define the 
actual image. The format of the image data is a series of single 
lines in quotes consisting of a period (.) where you want a 
background color pixel and a star (*) were you want a foreground 
color pixel. Spaces within the quotes are ignored, and the total 
number of . 'sand "s in each line must be the same multiple of 16 
(that is, one of 163238, etc \. The image is ended with a single 'V 
in quotes on a line by itself. So to create a lo \ -I checkmark image 
you could write 

MAGE 

■ >-ry boring rectangle 

" * " ; checkmark 

"* * " ; be sure you have the 

same n 

; I -s 

- * 

- e- . , ,, 



You will, of course, see your checkmark image in your menu, 
and when the source code is written out it will include the 
complete image structure. A pointer to that image structure is 
placed in the global variable CheckMarklmage', which you can 
place directly in the NewWindow->ChockMark field. 

If you use Lattke/SAS C or the a "Sk assembler, the output 
source code will contain instructions to correctly place the image 
data in CHIP RAM. Otherwise you may have to modify the 
output source code slightly toensure this takes place. (Image data 

that is not in CHIT RAM is not displayed, as we all know ) 



Command .WIDTH 

Format .WIDTH <widlh> 
remplate WIDTH <widehi*> 

Purpose lb set the width of the display window 

li your application uses a low-res screen, you may want to 

design its menu in a lo-res screen. To do this, simply use the 
WIDTH command followed b> an integer indicating the desired 
width of the screen and window (.WIDTH applies to both) you 

Wish to use llu- delault width is MO pixels (hires) WIDTH 
followed by a star C) resets the width to the default value. (Since 
you usethe.WID'l 1 1 command only once, you shouldn't need to 
use WIDTH *) Widths other than MO or 320 are not recom- 
mended. 

Examples 

.width 320 ;use a lo-res screen width 

width MO ;don'tneed to write this since MO is the default 

.width * .restore delault width (harmless, hut will 

icancel am pre\ ious .WIDTH commands. Normally 

jyouonly use .WIDTH once.) 



Command 111 K ,1 1 1 

Format HEIGHT <hoight> 

I emplate HEIGHT <height I •> 

Purpose To set the height of the display window. 

I II li .1 1 1 is similar to .WIDTH and is used in the same way 

to set the height of the screen ^i^\ window vou wish lo use Ihe 
default value is 200. and heights other that 200 or 400 are not 
recommended. HEIGHT followed In a st., r C) resets it to the 
delault 



Command DEPTH 

Format .DEPTH <depth> 
remplate DEPTH <depth I •> 

Purpose To set the depth ot the display window. 

Not ver\- useful, but was included for completeness You can 
us,- tins command to set the depth ol Ihe screen vou wish to use. 
The default value is 2. This command has no effect on the output 
source code file. .DEPTH followed by a star <*> resets it lo the 
default value. 
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Command W_DETAIL 

Format W_DETAIL <detailpen> 

Template .W_DETAIL <detailpen I •> 

Purpose To set the detail pen used by the display window. 

If you're experimenting with different windows and win- 
dow settings, you can use this command to set the New Window- 
>DetailPen field ot the window in which the menu is displayed. 
Usually, however, it you play with this value your menus will 
end up looking worse (if they can be seen .it all) I he default for 
this has been carefully set to 2, and you normally won't want to 

change it. .W_DETAIL followed bv a star (*) resets it to the default 
value. 



58 



AC'S TECH 



*«♦♦♦♦♦♦♦■ 
*♦♦♦♦♦♦♦♦« 



^♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦« 



♦♦< 
♦♦< 
♦♦< 
♦♦« 
t+i 
♦♦« 
♦♦< 
♦♦« 
♦♦« 
♦♦< 

♦♦« 
♦♦« 

♦♦« 
♦♦4 
♦♦« 

♦♦♦♦♦♦«♦♦♦♦♦♦♦♦♦♦♦' 
♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦' 



*♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦"* 

♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦♦* 



♦♦♦ 

♦♦< 
♦♦< 

♦♦« 
♦♦< 
♦♦< 
♦♦« 
♦♦< 
♦♦< 
♦♦< 
♦♦< 
♦♦« 
♦♦« 
♦♦« 
♦♦« 
♦♦• 
♦♦< 
♦♦< 
♦♦< 
♦♦* 
♦♦« 
♦♦* 
♦♦« 
♦♦< 

♦♦< 
♦♦' 
♦♦« 
♦♦« 
♦♦< 
♦♦« 
♦♦< 
♦♦« 
♦♦' 
♦♦< 
♦♦< 
♦♦< 
♦♦« 
♦♦' 
♦♦< 
♦♦« 
♦♦< 
♦♦• 
♦♦« 
♦♦< 
♦♦< 
♦♦< 
♦♦< 
♦♦« 
♦♦' 
♦♦' 
♦♦« 
♦♦< 
♦♦« 
♦♦< 
♦♦« 



♦♦' 
♦♦■ 



Command .W.BLOCK 

Formal .W_BLQCK <b1ockpen> 

Template W_BLOCK <blt>ckpen I •> 

Purpose To set the block pen used by the display window. 

AVJHX)CK is Similar to.W_DETAIL.and the same warning 
applies. The default value is 1. W_BLOCK followed by a star (*) 
resets it to the the default. 



Command ITEMEDGE 

Format ITEMEDGE <itemedge> 

Template .ITEMEDGE <itemedge I •> 

Purpose To set the Men u I tern- > Left Edge field lor each menu 

item belonging to a particular menu. 

It's easier to show how this command works than it is to try 
and explain it. Figure 1 shows the normal valueof the Menultem- 
>LcftEdge field. Usually it is zero, which means that the leftmost 
edge of item box is zero, relative to the left edge of the menu title 
bar. Sometimes, though, there are a lot of menu titles, and by the 
time you get to the last one, the item box runs off the edge of the 
window, even though the title bar fits (Figure 2). When this 
happens (which can be often if you use lo-res screens) the 
II I Ml U. I command can be used to push the item box to the kit 
Of the menu title box. and back onto the screen (Figure 3). The 
parameter for ITFMFIK.il- is always a negative integer repre- 
senting the offset in pixels from the menu header. You can have 
adifferent ITEMEDGE forcach item box if you wish. ITEMEDGE 
followed by a star (*) resets it to the default value, currently 0. 

Example: 

.itemedge -20;start the menu strip 20 pixels to the 

;lefl of the menu 
title box. 



Command .OFFSET 

Format .OFFSET <offsel> 

Template .OFFSET <offset I •> 

Purpose To set the amount of overlap of a sub-item box. 

.OFFSET gives you complete control over where a sub-item 
box overlaps an item box (Figures l.V'i I he parameter is an 
integer be tween-lOOand 100. If you specify- 100. the sub-item box 
appears at the leftmost position, relative to the item box A 
parameter of 100 will put the sub-item box at the rightmost 
position relative to the item box. The default value is 75. .OFFSET 
followed by a star(') resets it to the default. 

Example: 

.item "» Print" 

.offset -50 ;the subi box consisting of "NLQ" and "Draft" 

;will overlap about halfway 
over the left side 

;of the item's select box. 
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Figure 4: Subitcm box with .OFFSET = 100. 



♦♦♦ 
►♦♦ 

►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
>♦♦ 
►♦♦ 
>♦* 
►♦♦ 
►♦♦ 
>♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
»•** 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 
►♦♦ 

lit 

m 



.subi "NLQ" 
.subi "Draft" 
offset ' 



usei tor next sub-item box 



Command MODI 

Format .MODE <drawmode> 

Template MODE <JAM1 I 1AM2 I INVERSVID I 

COMPLIMENT I '> 

Purpose Toset the lntuiText->Draw Mode field of an item or sub- 
item. 

You can use this command to set the InluiText->DrawMode 
field of the IntuiText structures for items and siib-ilems encoun- 
tered after this command. It may be used more than once to set 
different modes fordilferent items. If <drawmode> is |\\I KS\ II). 
thecurrentmodeisOK'd with this value instead o! replaced. The 
default is |AM2; MODE followed by a star (') resets it to the 
default If you aren't sure what the various drawmodes are. it's 

best not to use this command 



Example: 

.mode JAM 1 
item "Jam 1 item" 



;heldisJAMl 

.mode|AM2 
.item "Jam 2 



tern" 



this item's lntuilext->DrawMode 



:this item's Intui Iext->DrawMode 
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.held is JAM2 

.mode" 
default 



.reset to 
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Command IT.TOPEDCE 

F0rm.1l II lOI'l I H.I ■ (o|v ( :. 
Template II IOPEDGE <topedgel*> 

Purpose lo sd (he Intuilevt -top! dge tidd (or items and sub- 
items. 

This command is used to set the lntuiText->TopEdge field 
tor items and sub-items encounters after the command. The 
default value is 1. and normally it won't be necessary to change 
it. .IT.TOPEDCE followed by a star (*) resets it to the default 
value.- 



Command .IT_FKO\iri \ 

Formal IT_FRONTPE\ <frontpen> 
Template ITJ-RONTPI \ <frontpenl*> 

Purpose To set the lntuiText->TopEdge field for items ami sub- 
items. 
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Figure 5: Subitcm box m nh .OFFSET =75 



This command set- the lntuil"ext->FrontPen Held for all 
items and sub-items encountered after it Its use i-> identical to 
JT_TOPEDGE Fhe default value is 2, and .IT FRONTP1 

lowed by a star (') resets it the the default 



Command .IT_BA< KPI \ 

Format TT.BACKPEN <backpen> 
Template JT_BACKPEN<backpenl a > 

Purpose To set the lntulText->BackPen died tor items and sub- 
item-. 

You use this command to set the lntuiIe\t->BackPen field 
for items and sub-items encounters after it. It-- use is identical to 
rr.FRONTPEN. The default value is 1 and II BACKPEN fol- 
lowed by a star n resets it to this 



Command 11 1 1 1 11 ix.i ffj 

Formal ll LEFTEDGE <leftedge> *•♦< 

remplate 1 1 I.EFTEDCE<leftedgel*> TT* 

Purpose To set the Intui le\i->l ettEdge field for items and sub- *>«>« 
items 44i 

ft i 

I his command sets the JntuiText->LeftEdge field for all #>♦« 

items and sub-items encountered after you use it. The default JJi 

value is 2, and ■ resets it to the default value— useful if you want «•♦< 

.1 menu that allows the user to choose between colors. This is a ♦♦< 

common menu in many commercial applications and it iseasylo X%4 

construct with MenuScripl as follows: ♦♦< 

♦♦< 



, this menu displays lour solid color Kirs tor items and 

; lets the user select among them 



the 



menu "Select Text Color" 

it Jeftedge 20 Ipush the left edge of text window to 



pixels 



; right 20 



.it_backpenO;since we just want blank space of color 



.the following item is just blank space in color 0. 
ills checkable and initially checked. When we select 
this item (item 0) items 1.2,3 are excluded. We use 

.box highlighting 



item " " checkable check toggle box exclude 1.2,3 end 

Similarly for colors 1.2,3 

• 

.it_backpen 1 

.item " '* checkable toggle box exclude 0A3 end 

.il_backpen 2 

.item " " -he- k.ible toggle box exclude 0,1,3 end 
.it_backpen 3 

Item "checkable toggle box exclude 0.1 ,2 end 

,it_baekpen • .reset to default 
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Command A mH Kt I 

Formal AMUKU 

remplate \ SOURCE 

Purpose Ho create assembly language source code for the menu. »♦* 

♦♦« 

Phis command is identical to the -a switch. 

f>f>4 

♦♦« 
♦♦< 
44< 
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Command II sH K( I 

Formal .B_SOURCE 

Template I! SOURCE 

Purpose To create AmigaBask source code tor Ihe menu 

This command is identical to the -b switch. 



Command C .SOURCE 

Format .C_SOUR( I 

Template .C.SOURCE 

Purpose I oereateCsourcecode for the menu (this is (he default). 



This command is identical to the -c switch. 
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►♦♦ 

Instead of complement highlighting, when this item is se- ►♦♦ 
lected, the text "Select r«t" appears ^^ 

►♦♦ 
Example IXX 



item "Exclude Item " checkable. toggle.cx.lude 1,7,1 end 
.il we select "Exclude Item", items 3,7. and I of this menu 
are unselected 



t nnitnand SELECT 

Formal SELECT <name> 

template SELECT "Select Text" 

Purpose I o define alternate text to he displayed when this item 

is selected* 
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Parameters 

Hereare the parameters which mav follow an. II l : M or .SUBI 
command. 

Parameter CHECKABLE 

Format CHECKABLE 

Purpose To make ,\m\ item checkable. 

I he item is checkable, but is not initially checked. You are 
responsible for leaving enough room on the left for a checkmark. 
Using this parameter is equivalent tosetting the CHECK1T flag of 

the Menultem->Flags field.— 



Command CHECK 

Format CHECK 

Purpose To initially check an item that is checkable 

If the item is "checkable," then it is initial!) checked. Using 
this parameter is equivalent to setting the CHECK flag or the 
Menultem->Flags field. 



Command TOGGLE 

Formal TOGGLE 

Purpose To be able to toggle the checkmark for this item. 

This is equivalent to setting the MENUTOGGLE flag of the 

Menultem->Flags field. 



Command EXCLUDE 

Formal EXCLUDE <itemnum>" END 

Purpose Toselectwhichitemsare mutually excluded by this one 

For a "checkable" and "toggle" item, this s,i\s to mutually 
exclude each menu item in Ihe <itemnum> list. Items are num- 
bered starting form 0. The list is terminated with the END 
parameter. 



.when item "Fred" is selected, "...And Barney" appears 
item "Fred" select " ..And Barney 



Example: 
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Ml M HEADER 



ITEM I 



M IUII M i 



si iuiim : 



ITEM 2 



II I M 3 



(>| I SI I : -lid) 



Figure'- Surtik-m box with OFFSET a -|00 



Command OFF 

Format OFF 

Purpose To initially ghost this item. 

I sing this parameter is equivalent to clearing the 

ITEMENAB1 E 1 1 flag ol the MenulternoFlags field. 



Command KEY 

Format KEY <command key> 

Purpose To define a command key equivalent tor this item 

MenuScript automatically creates enough room at the end of 

the item tor the command key (hi- or lo-res). so you don't have to 
worry about leaving enough room on the right. Note that <com- 
mand key ■ is not enclosed in quotes 
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Specialists 
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Commodore authorized full 
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parts. Complete in-shop inventory 

Memory Management, Inc. 

3% Washington Street 

Weltesley, MA 02181 

(617)237 6846 



MenuScript di>es no! specify where in the line the error 
occurred, bui sine thin- is only one command ,i I lowed per line, 
this shouldn't be a problem. 

(-1) ER_BREAK Not an error. If you pressControl-c.it any time 
(except when the menu is being displayed) MenuScript termi- 
nate- gracefully with this message 

(0) ER_\OJRRORS Everything's line 

(1) IR.NOJNTUITION Major problem. MenuScnpt was un- 
able to open the intuition.librarv. 



(2) ER_UK_SW1TCH 
command switch. 

O) ER_NO_INI*UT 

input file 



MenuScript doesn't recognize vour 
MenuScript was un.ible to open your 



Circle 104 on Reader Service card 



Example: 

;this item can be selected by R-Amfga / 
item "Us*- / to select this item'' key Z 



Command ( OMP 

Format COM!' 

Purpose I o select complement highlighting for this item. 

< I his is the default, so you don't have to specify.) 



(4) ER_INVAUD_TOKEN 
recognized. 



Your command was not 



Command BOX 

Format BOX 

Purpose Toselect BOX highlighting for this item. 

This command is equivalent to setting the HIGHBOX flag of 
the MenuItem->Flags field 



Command \0\| 

Format N(>\l 

Purpose To select no highlighting for this item. 

Using thiscommandisequivalent to setting the HICHNONE 
flag ol the Menultem->Flags field 



Error Messages 

When MenuScript detects an error, it stops reading the file 
and prints the following: 

■ line number> : <offending line> 

ERROR: (error number) <short description of the error> 



(5) ER_NO_ARG There is no numeric parameter for a 
command which requires one. 

(6) ER_NO_SCREEN MenuScript was unable to open a 

screen todisplay your menu. This is probably due to low memory. 

(7) ER.NO.WINDOW MenuScript was unable to open a 
window to display your menu. This is probably due to low 
memory. 

(8) ER_2_FO\T The FONT command may be used only once. 

(4) ER_NO_CRAPHICS Major problem. MenuScript was un- 
able to open the "graphics. library". 

(10) ER_NO_DtSKFONT If you usethe FONT command with 
a disk-based font, MenuScript tries to open the'diskfont.library". 
You get this error if it was unsuccessful. 

(11) ER_NO_FONT The font specified inthe FONT com- 
mand could not be opened. 

(12) ER_NO_MEM MenuScript allocates all memory dy- 
namically, so the number of menus, items, and sub-items is 
limited only by available memory. When you run out of memory, 
you get this message 

(13) ER_NO_MODE The parameter given for the MODE 
command is not recognized. 
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(14) ERJTEM 
command. 

(15) ER_SUB1 
command. 



1 hi- SUBI command was used beforean .ITEM 



(16) ER_NO_QUOTE Missing quote character in a <name> 

parameter requiring quotes. 
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(17) ER_1NVAUD_ARC 
of range. 



Parameter is not recognized or is oul 



(18) ER_INVAUD_OFFSET 
must be between -100 and 100. 

(19) ERJNVALIDJTEMEDGE 
must be <= 0. 



The .OFFSET parameter 



The.ITEMELX.K parameter 



(20) ER_M1SSING_END When you use the CHECKIMAGE 
command, your data must be terminated with a """. 

(21) ER_STACK_OVERFLOW Thts shouldn't happen un- 
less you use more than 64 separate menus at once. Bui you can 

have as manv items or sub-items for each menu as can be fit on the 
screen. 



Putting It All Together 

If you have access to the 1 .3 Amiga ROM KERNAL Reference 
Manual: Libraries & Devices, you may want to look at the C source 
code for the example menu on pages 125-127. Here we will 
construct precisely the same menu with MenuScript. 

For the first menu, the title shiuiKI he Project", and the items 
are"New"."Open...","Save","SaveAs...","Print","About ".and 
"Quit". Including the command key equivalents, the first lines of 
our MenuScript program will look like this: 



.menu " Project " 
.item "New" 
item "Open" key O 
.item "Save" key S 
.item "Save As..." 
.item ">> Print" 



;thisilem has command key equiv'O' 



;this item has sub-items 



Now the "» Print" item has two sub-items, "N'LQ" and 
'Draft" so we continue by writing: 

.subi " NLQ " 
.subi " Draft " 
And finally: 



.item "About" 
item "Quit" key Q 

We're now done with the first menu, 
similar: 



The other menus are 



menu " Edit " 
.item "Undo" key / 
.item "Cut" key X 
.item "Copy" key C 
.item "Paste" key V 
.item "Erase All" off 



;Edit menu 



;this item is ghosted 



.menu " Preferences " 

.item " Sound " 

;"Havc your Cake" excludes "Eat it too" 

.item "Have Your Cake" checkable check exclude 3 end 

;"Eat it Too" exclude "Have Your Cake" 

.item "Eat It Too" checkable exclude 2 end 
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Circle t05 on Reader Service cord. 

If we feed this hie to MenuScript. we get the exact menu listed 
on pages 1 24-127 of the RKM, with considerably less effort on our 
part. The complete listing for 'rkm.menu' is given in Listing 2. 

Inside MenuScript: The Program. 

Now that we've teamed how to use MenuScript. we look at 
one of the more interesting aspects of the MenuScript program 
itself. Essentially what MenuScript does isto translate the instruc- 
tions found in the input file intoa complete Menu structure. Once 
this is completed, the task of displaying the menu and writing out 
the source code is relatively simple. The heart of the translation 
procedure is parsing 

Parsing is the process of splitting complex input into smaller 
elements which can be processed one .it a time. For example. 
when a C compiler encounters an expression like(x+y)/(B-A>, it 
cannot digest the entire expression at once. Rather, it must split 
this expression into smaller pieces: i.x.+,y,)./,...etc. . processing 
each small piece separately. 

Parsing is a vast theoretical field within computer science. 
and of course there is no single correct vva v to parse input. Which 
method is must etl u ient depends much on the particular applica- 
tion, since what works with one application may not work at all 
with another. The trick is to select the most efficient method for 
(he type of input that is expected. 

So we have to start with a precise definition of exactly what 
kind of input MenuScript expects I lere there are several choices, 
and each can lead toa different parsing technique. In MenuScript, 
we expect a series of statements with (possibly)comments mixed 
in. A statement can be either a command by itself (.A_SOURCE> 
or a command followed by one or more parameters (.WIDTH 
320). If only one statement is allowed per line, we essentially have 
a script. The first question we might ask, then, is whether to allow 
more that one statement per line. Would this make parsing more 
or less complicated? 



(continued on p. 761 



Volume 2, Number 2 



♦♦4 
♦♦< 
♦♦< 
♦♦4 
♦4M 
♦♦4 
♦♦4 
♦♦4 
♦♦< 
♦♦4 
»4H 
•4H 
♦♦< 
♦ ♦« 
*4H 
♦♦« 



♦♦4 
&<M 
♦♦4 
♦♦4 
♦♦< 
♦♦4 
♦♦< 
♦♦4 
♦♦4 
♦♦< 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 

tti 

♦♦4 
♦♦4 
♦♦4 
4»4M 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 
♦♦4 

♦♦4 
♦♦4 

tr< 

♦♦4 

♦♦4 
♦♦4 
♦♦4 
♦♦4 

♦♦4 
♦♦4 

£9 

♦♦4 

» 

♦♦4 
63 *>«M 






BUT YOUR LINES 



THE FASTEST DRAWS IS THE WEST 

by Thomas I. Esheltrun 



This article consists of an in-depth tutorial concerning the 
ti rawing of lines on the Amiga's display screen by means ( . i ilir.xi 
communication with that part of the Agnus chip hardware, 
commonly referred to as the "blitter." This is not a commonly 
discussed subject. Therefore, even if you find it a bit outside you r 
present graphics programming requirements, you may still wish 
to make note of it and file it for future reference 

To Dazzle Is to Boogie 

Many programmers writing in different programming lan- 
guages have effectively used the Move() and Draw{) functions 
from the Amiga graphics library todraw lines on the display. This 

is fine in the vast majority of situations, but what alternatives exist 
for someone who wishes tocreatea moreexotic, visual "stunner"? 

Say, for example, to get the job done, we must draw many 
thousands of lines each second using some simple algorithm, 
perhaps employing as input, the output from a random number 
generator. The results of something like this can be breathtak- 
ingly beautiful. 



All line draws are handled for you by the blitter. The simple 
Draw() function contains much underlying code and time-con- 
suming overhead, but eventually, the blitter receives commands 
it understands and carries them out. If you want to "dazzle the 
natives," you must avoid this overhead and eliminate all non- 
essential code. You must learn to cause the blitter to draw lines by 
directly coercing it to do so. Given the realization that speed 
means everything, we must consider programming in assembler. 

If that last word caused a few heart palpitations, calm down! 
Assembler is the simple*! of languages, because it has no syntax 
as such. You must learn a few dozen, common instructions out of 
more than UK). You will find many fine assemblers on the market 
at very reasonable prices, especially when available discounted. 
In the process, you will develop a much greater understanding of 
whatever happens to be your high level language of choice. Take 
your time, and learn new commands as you go. Another good 
reason to code in assembler is the availability of several powerful, 
consistent and easily -used symbolic debuggers. My personal 
preference is the MetaScope by Metadigm. Assembler is made to 
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BUTTER LINE MODE REGISTERS AND THEIR CONTENTS 



Offset from SdffOOO 
Chip Base (in hex) 



052 



048 
054 

064 
062 
060 
074 
072 
044 
058 



AMIGA 


Contents Of 


Opening 


NAMES 


bit settings. 


remarks 


BUAPTL 


2 ' Sdeita - Ldeito 


See Deltas 


BLTCPTH 


Holds address of word 


Rel offset 


BLTDPTH 


where line starts. 


screen OX) 


BLTAMOD 


2 ' Sdetta - 2 * Ldeita 


See Deltas. 


BLTBMOD 


2 ' Sdeita 


See Deltas. 


BLTCMOD 


Screen Width 


Usually 40 


BLTADAT 


S8000 


Constant 


BLTBDAT 


Line mask. 


Solid = Sff. 


BLTAFWM 


SFFFF 


Constant 


BLTSIZE 


Set bits 0-5 at 2. 





040 



BLTCON0 



BLTDPTH. 



042 



BLTCON1 



Set bits 6-15 at Ldeita* I, 
Ldeita* 1 is the line length in points. 
Ldeita of zero indicates 1 024 points. 
BLTSIZE TRIGGERS DRAW. Load It Last!! 

Bits 12-15 contain the offset of the 
line's starting point within the 
16-bit WORD contained in BLTCPTH and 
obviously, the latter can be 
accurate only to within 16 bits. 
These four bits pin it down. 

Bits 8-11 are set 1 101 respectively. 
This is a constant value. Sb 

Bits 0-7 are set at SCA respectively. 
This is the "MinTerm," the value of 
which causes the line to stay in synch 
with any mask you put in BLTBDAT. 
YOU MAY VARY THIS for "effects- 
Bits 12-15 should be set same as 1 2- 1 5 
in BLTCON0 while learining. 
Bits 7- 1 1 are always set to 0. 
Bit 6 is set IF 2 " Sdeita < Ldeita 
Otherwise it is reset (0). 
Bit 5 is always set to 0. 
Bit 4 is the SUD bit. See Octants 
Bit 3 is the SUL bit. See Octants. 
Bit 2 is the AUL bit. See Octants. 
Bit 1 is set if you want but one point 
to appear on a display tine. (Fills) 
Bit MUST be set to put the blitter 
into line draw mode. 
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appear difficult by some professional gurus, (or the same per- 
verted reason that doctors and lawyers use Latin terms. Il makes 
them stand out as doctors and lawyers — and in our case, gurus. 

There is one alternative to writing everything in assembler, 
but since it may be compiler dependent, I won't address it in 
depth at this time. It does make sense to write functions in a high 
level language whenever speed is not essential. These functions 
can call other functions, which have been written in assembler 
either because speed is of the essence, or because they will be 
called a multitude of timesduringprogramexecution. Arguments 
can be passed back and forth between the high level function-* and 
the assembler routines on the stack with ease, at least in the case 
of the C language. For example, in the code accompanying this 
article, we could have opened the graphics paraphernalia using 
C functions, thereby saving writing a lot of code. Only the line 
drawing routine itself mustnecessariiy be in assembler. Note also 
that it is the only function called repeatedly. 

The object of thisarticle is toexplain the rudiments concerning 
how a graphics engine draws lines. This is hardlv something we 
want to relearn every once- in -a -while throughout our lives, so we 
will create .1 few, permanent routines that we can use repeatedly. 
Basically, we want to create real "hotshot" MoveQ and DrawQ 
routines of our own. 

Language of the Slitter 

Admittedly, this is not something simple enough to be 
learned via osmosis. The part that is quite complicated is the 
"language" of the blitter. This article will not go intodetail on how 
to move data with the blitter, which is its primary raison . Vein: The 
writer assume* you know at least a little something about the 
blitter generally. Rather, we will go into details on using the 
blitter "Line Mode" to draw — guess what— lines! This Mode is 
not well-documented in commonly available, Amiga literature. 
You will find an in-depth discussion of the subject in Dittrich 
Schemmel's seminal work published by Abacus. Another good 
source is the file entitled "LineBlit.Arc" written by Mark S. 
Adams and published by Geodesic Publications. One of the best 
examples of good assembly programming and blitter techniques 
may be found in the David Ashley "TumbluV Tots" tutorial and 
game code that appeared in Amazing Com/ui/iM^, V3.8. 

The blitter can draw lines of up to 1024 pixels in length. 
I lowever, this is not just a matter of describing two points and 
then connecting them To master the blitter, we must write a 
routine that takes the descriptions ot two points, translates them 
as written in "Cartesian talk" (xl.yl and x2,y2) into "blitter talk," 
loads the blitter, and causes it to draw. It is essential to know why 
the routines work so that you may alter them to your own 
purposes — to draw patterned lines or lines in inverse video. 

As you read on, you may realize that the data we input into 
the blitter really boils down to a starting address in the bitmap 
indicating where to begin the line, an Octant code indicating in 
which display area we wish to proceed from that starting point, 
some Delta data which describes the angle we will take, and the 
length of the line to draw. "Blitter talk" is just as reasonable as 
Cartesian values. It is simply "strange" to us amateurs. This 
seems to cause everyone a temporary, mental block. 



Blitter Control Registers 

You probably know that the registers of the Amiga 'scustom 
chips are "memory mapped." Translated, this means we can use 
them just as if they actually were addresses in memory. The base 
of this custom chip "memory" is given what amounts to a 
fictional address, towii:0xdff000orSdff000. Instead of offsetting 
from this base by a constant value, say 64, (this is the same as 
saying Sdff040) in order to load or read a particular register, your 
Amiga compilers and assemblers alt use standard "defines or 
"equates" to translate the cold, meaningless number, (64 or hex 
40) into a short, descriptive name, say BLTCON0, for example. 
Therefore, BLTCON0 would be the same as saying Sdff040. You 
may immediately recognize the string "BLTCON0" as signifying 
the address of the "first blitter control register." In any event, this 
is much easier than remembering what data belongs in good, old 
Sdff040! Unfortunately, the Amiga naming scheme for these 
registers is of far greater significance when the blitter is used to 
move memory, as it usually does, than it is for when it is used 
merely to draw lines. 

In order to draw lines, we must learn what values are meant 
to be loaded into these registers set aside by the Amiga engineers 
as the blitter registers. The difficult part is the esoteric nature of 
main ot these values. At this point, study Table A for .1 few 
minutes. It is important that you familiarize yourself with the 
terms being used in Table A without yet being unduly concerned 
with what they mean. 

Deltas — Coordinate Differences, or Steepness of 
Slopes 

If I am not mistaken, your attention was primarily attracted 
toall the Deltas of onesort or anotherencountered when reviewing 
Table A. The time has arrived to see exactly to what thev refer. 

The coordinates of a line's starting and ending point are 
referred to as XI, YI and X2, Y2, respectively. These are "Carte- 
sian" values relative loan horizontal "X" and a vertical "Y" axis. 
In the case of the Amiga, the "X" axis runs from the left edgeof the 
display to the right, and the "Y" axis runs from the top to the 
bottom edge. Our coordinate values are relative to the top-left 
point of the display which has the arbitrary value of 0, 0. 

Tor our purposes, DeltaX is said to be an absolute value, 
equal to thedifferenceof X2 - XI as defined above. DeltaY is said 
to be the value equal to the difference of Y2 - Yl. These values 
must be massaged a bit more before feeding them to the blitter for 
action. 

There are three terms mentioned in Table A to be loaded into 
the blitter. Tocompute them, we must first compare DellaX and 
DeltaY. The smaller of the two is hereafter referred to as Sdelta 
(smaller difference value). The larger is hereafter referred to as 
[.delta (larger difference value). Now Table A will begin to make 
sense; 

First term = 2 * Sdelta (Loaded into BLTBMOD) 

Second term = 2 • Sdelta - Ldelta (Loaded into BLTAPTL) 
Third term = 2 * Sdelta - 2 • Ldelta (Loaded into BLTAMOD) 



These rather peculiar values are the ones ingested by the 
blitter in order to properly locate your line. For now, you must 
either accept them, or acquire a Ph.D. in geometry. I know which 
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route I took! At least their calculations don't require very much 
coding. 

Before leaving the subject of Deltas, there are two other 
points worth mentioning hrst. If vou stop and reflect upon it, 
Ldelta will be the same as the number of points in the line, less 
one. The reason it is "less one" is simply because it is computed 
via subtraction. Thus, by definition, it is one short. 

Secondly, and more importantly, in the event that (2 "Sdelta 
- Ldelta) is negative, the so-called SIGN bit, bit number 6 of 
BLTCONO must be set. Take a look right now near the bottom of 
Table A, so as to cement this into your mind. It is clear! v identified 
by the presence of two asterisks. 



Octants— The Companions of the Deltas 

Hie line's "octant" is another unusualcomponent. The blitter 
isa true graphics engine, and therelorc, it needs to know about the 
octants into which your display area is divided. The blitter sees 
the overall display divided radially into eight parts. It make-- use 
of a "code," assigned toeach of the particular octants, to determine 
which direction the line is to be drawn. 

An octanlS corresponding "code" can range from to 7 
inclusive, and therefore, can be represented in binary by a com- 
bination of three bits. These bits have names The names are as 
follows: 



TABLE B 




RELATIONSHIP OF LINE COORDINATES TO OCTANT CODE 






Line coordinates 
such that: 


Octant No. Code No. 


SUD 


SUL 


AUL 


xl <=x2 

y2<=yl 

Dettav <= DeltaX 





6 


1 


1 





x1<- x2 
y2<=yl 
DeltaX <= DeltaV 


1 


1 








1 


x2<-xl 
y2<«yl 
DeltaX « DeltaY 


2 


3 





1 


1 


x2<-xl 

y2<=yl 

DeltaY <= DeltaX 


3 


7 


t 


1 


1 


x2<=xl 

y1<=y2 
DettaY <= DeltaX 


4 


5 


1 


o 


1 


x2<=x1 
yl<=y2 
DeltaX <= DeltaY 


5 


2 


o 


1 





xl<=x2 
yl<=y2 
DeltaX <= DeltaY 


6 














xl <«x2 
yl<*y2 
DeltaY <« DeltaX 


7 


'■ 


1 
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] Sometimes Up or Down (SUl» 

2. Sometimes Up or Left (SUL) 

3. Always Up or Left (ALL) 

When referring io the binary number formed by these three 
named bits. SLI) is always the most significant bii. and AUL is 
always the least significant bit. 

Observe thai these three "friends" get loaded into hits 4. 3 
and 2 respectively ot the register 1(1 ICON I. Admittedly, here we 
must do a disproportionate amount of calculation for the number 
of hardware bits we get to load -is the fruits of our effort. 

This is a good time to use the data appearing below to draw 
yourself a diagram to studv along with the rest ol this subject 
Draw a horizontal line, starting at the center of a sheet of paper, 
extending to the right, and mark it '0 degrees.' Draw from that 
line, counterclockwise, eight segments of 45 degrees each. While 
thus drawing this out in circular or radial form on paper, you will 
familiarize yourself with the kliosyncrades of octants. This may 
be a nuisance, hut hear in mind this is the most eccentric part ol 
drawing lines at warp speed. Furthermore, vou will ever have to 
write them Only once. Our object is the creation ol a black box 
routine that you may use forever— or al least mure than once. 

Segment I \ tant No. Code No. SUD/SUL/AUL 



o to 43 degrees 

45to9C degrees 
90 to 135 de ; 
135 to 180 degrees 
180 to 223 degrees 
225 in 271) degrees 

270 to 315 degrees 
315 to 360 degrees 



Table H shows how we use those Delta calculations de 
scribed above to relate to the pertinent Octant, and hence values 
forSUD, SUL and AUL which we will need for blitter loading. 

Miscellaneous Bits and Pieces 

The line is effective!) drawn in 16-bit lengths which repeal 
throughout the length of the line. You are entitled to prepares 16- 
bil mask and "AND" this with each "line piece" as it is drawn, so 
that the result is a patterned line Ibis mask is placed inside the 

BLTBDATregistei Sffor nil 1111 would produce a solid line, 
whereas 1010 1010 would produce a dotted line. etc. 

Bit lofBLTCONl is the "single bit.' sometimes known as the 

SING" bit This must be set If you have an) intention of utilizing 

your line as the outline ol an area which will be subsequently 
filled by the blitter. The SING bit being set guarantees that two, 

adjacent pixels shall not be drawn on the same line of the display 

while drawing in the Line Mode, which otherwise is .mite a 
common occurence. The reason this must be prevented is that. 
while the blitter appears to draw a "fill" as if it were a "solid area 
draw," it in fact fills the area line by line The blitter draws from 
left to right, across each line ol the display, in order to effect the 
"fill". It Senses the ana outline and begins the "draw" when 
encountering the first pixel on a line of the display It stops 
"drawing" whenever the next previously drawn pixel on the 
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same display line is encountered. Hence, two successive pixels 
drawn while in "Line Mode" will cause disaster when encoun- 
tered by the blitter in a subsequent "fill" mode. It simple won't 
fill, and it will go totally out of sync. 

Bit of BLTCONI is the I 1 NE bit. This must be set in order 
that the blitter knows that the data you put in its registers is meant 

to be used for the purpose of drawing lines, not copying memory 
blocks. I his bit sets the "line draw mode." 

The registers BLTCITH and BLTDPT1 1 are loaded with the 
address of the word which contains the first point of (he line to be 
drawn. The bliiter takes care of shifting this point around within 
this word, thanks to that mask weextracted from the old coordinate 
and placed intobits!5-12of the BLTCON registers Stv Interesting 
Algorithms," below. 

Program Outline 

To perform a direct blitter line draw, we first convert a set of 
coordinates into an Octant code and determine an Ldelta and 
Sdelta. Secondly, we calculate tin- address within the bitplane 
where the line will begin. Then, we must call two routines to 
prevent other processes, from accessing the blitter while we are 
busy loading it, and finally, we load our computed values along 
with some -a stem-mandated constant values into appropriate 
addresses (blitter registers). Beware! The instant the register 
HI I SI/1 is loaded, the line is drawn. 

I he program begins with a few lines of code that permit us 
tosense it it was begun from theCl.l or the WorkBench. The latter 
demands a little more overhead that is fully explained in many 
other sources. With the graphics library opened, we branch to the 
routine, "playfields."IK'ro,wouilllhi'variousgr.iphk>. primitives 
to produce for us a single plav held upon which we can draw our 
beautiful lines. Again, this code has been fully delved into by 
many other writers 

We next enter the loop algorithm out of which we will call 
drawjine", our routine of interest. Don't let the algorithm 
contuse you. What happens is thai you get a sequence of v arying 
pattern, full-height lines drawn from one screen diagonal to the 
other I his is followed by a series of patterned, full-width lines 
beginning at the diagonal last mentioned and continuing to the 
diagonal we first started with, i-very eighth full sequential series 
sees a new color register being loaded for a "cycling" effect. 

With every lull sequence, the hardware is checked Io see it 
the user is depressing (he left mouse button. If it is depressed, the 

code drops into its closing routine where everything allocated is 
returned and the Workbench message replied to, in the event this 
was begun trom an icon. 

Interesting Algorithms 

In order to determine the precise point where the line draw 
shall begin, we have an inherent problem along the horizontal 
axis in that the address of the smallest unit we are capable of 
computing is that ol a byte I uckily, the blitter is capable of 
shifting around inside a word to the precise bit (pixel) at which it 
is to draw. If we can compute how many bytes or words from the 
base address (I | the bitplane the line is to begin, and hem many 
hits iiis to shift once it arrives, n the start of thai byte or word, the 
blitter can take it from there, and draw on the precise XI coordi- 
nate requested 
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Byway of further illustration, consider the fact that all bits in 

a binary number above the lowest nybble necessarily combine by 
themselves into a value that is evenly divisible by R and 16. Ex: 
decimal 51 is 0000 0000 0011 0011. The value of the bits above the 
least significant nybble is 48 decimal lb this, one adds the value 
in that low nybble. which is decimal 3. We then have the full, 
decimal equivalent. We want to extract and save the value ol this 

low order nybble. This is done in the program by "AND M -ing it 
with hex Sf. The result is the value we must shift beyond an even 

byte or word alignment to arrive at the pixel where the line draw- 
is to begin. 

Eventually, we will divide the value in XI by B using the 
asrw instruction, which will yield a whole, even number of bytes 
For example, 51 divided by 8 is 6, meaning our XI point must be 
just a tad to the right of byte number h in line Yl. 

To compute our address, we need only look at VI to see how 
many lines down rrom the top our line draw begins. Multiply this 

value bv the number of bytes per line. In OUT lores screen this is 
40 (40 * 8 is 320). To this value, add your XI bytes (6 in our 
example) and. voila!, you have the number to add to the address 
of the plane's base tocome to the precise address where the line 
draw begins I he shift value (3) goes into a special register, some 
blitter saves you the nuisance of the detail work. The address ol 
the plane's base, of course. Is found and stored tor us by the earl) 
call to the system routine, InitBitMapt). 

Thoseof you not familiar with assembly programming should 
keep your eye open for the progress ol this algorithm in the code. 

Another thing to observe is that each time the code tests for 
the deltas by subtractions, a value is moved into register d7 Ik- 
apprised that the value moved is more than merely the i Vt.uii 
Codebits On each occasion, weare setting Hit i> (the I l\l bit)and 
resetting Bit 1 (the SING bit) in addition to the Octant Code bits. 
SUL, SUD and AUL. Eventually, \ou will see thai we load the 
wholethingintoBLTCONl at uive.ilK'iel'v setting many disparate 
bits- 

The final algorithm that bears commenting concerns color 
indirection. Thisparticularcihle will clarit\ am misunderstanding 
you may have regarding that subject. Observe that a color register 
value is placed in memory at the location called "fillcolor." We 
have called for a screen "Depth" of threebitplanes. This allows us 
eight colors— 000 to 111 inclusive. Let us step through the code, 
assuming we placed a '5' in fillcolor. and thai our "colortable" has 
the value of 500f (dark blue) in the sixth spot ol the eight possible. 

For the discussion below, let me just mention that the term 
"MinTerm" refers to a binary value which causes the blitter to 
impede, permit, or alter data being moved by it through its 
various DMA channels. You don't need to be overly concerned 
about this unless you want to move entire blocks of memorv 
using the blitter. Meanwhile, you are free to experiment with the 
values of MinTerm. 

The address of the first bit plane is loaded into d7, and hit in 
"fillcolor" istested.lt proves to be true ('5' being binary 101). This 
causes the MinTerm SCA to be loaded into BI.TCON0, thus 
turning on the DMA channels, so that thebitsof the first plane will 
be set wherever the line is to appear. By incrementing dl. we 
cause the next (second) bit of "fillcolor" to be examined. Bit 1 
thereof proves to be false, of course. Therefore, the MinTerm #0A 
will K- loaded into BLTCON0, thus turning off the DMA The 
contents ol register A2 are incremented so that we now point to 
the second plane.Now.the bits of this second plane will be zeroed 



wherever the line is to appear If you repeat this, you see where 
the bits in the third plane are once again set. Finally, when the 
number of the bit being tested (3) is the same as the screen 
"Depth' contained in d2, the loop quits because the line is totally 
drawn. To the eye, the combination of the odd planes (t and 3) 
being set and the even plane reset will present us with a dark blue 
line. The value preset in register 101 (SOOf) will cause the blue 
electron gun to turn full on, while shutting off the red and green 
guns , ompletelv I hUfi "gunned." our line will be drawn. 

Conclusion 

Commercial assemblers are relatively inexpensive. They 
work more quickly than compilers. You can do an edil-eompile- 
run sequence in a few seconds. Once you get in a groove, it will 
be time to acmiireagood symbolic debugger. This tool will enable 

you to catch programming errors you never knew you were 
capable ol making' I reter to s, rewball," unexpected results, not 
simple system crashes. The former are found only with the 
greatest of difficulty when programming in a higher level lan- 
guage 

It will be helpful tor you to experiment With my code See lor 
yourself what changes you can bring about. The code is rather 
sturdy, and will stand a lot of poking about. In any event , it should 
approximate the very fastest line draws n is possible to achieve. 
Hie whole point of this article is for you to excise the "drawjine" 
routine from the source code for use by yourself in your own 
programs- 1 should add that the executable of this program has a 
si/e ol less than 1500 bj tes! 

Once you rcali/e thai assembler programming is not difficult, 
and begin to experience the power you have, you will probably 
find yourself working a lot with Intuition in a high level language 
but assembling the algorithms that do your "grunt" work, Enjoy! 
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Ifyou program on the Amiga.soonerorlateryou will have an 
Operation lh.it requires the user to wait If your program is 
performing ,1 visible or audible action, the user has an 
indication the program is proceeding and will wait (or the action 
to tinish. On the oilier hand, if your program is accessing a device 
or performing some lengthy math routines, the user only knows 

th.it nothing happens when he continues typing or selecting with 
the mouse. In these situations, il is helpful to indicate that the 
computer is busy by changing the pointer to an image that 
conveys the concept of being busy or waiting. It is relative)) easj 
to change the pointer to the familiar Intuition /.Z cloud or a clock 
image by calling Vtl\nnter(l and C learPointerO, but it is much 
more interesting to animate the pointer. 

In this article, I will first explain the evolution of routines to 
animate a busy pointer. Second, 1 will explain how to replace the 
SetPointerO function with custom multitasking C routines with 

\er\ little programming overhead.'! he third section explains the 

demoprogram which allows you to see an animated busy pointer 
in action and moditv the delay and priority. The remainder of the 
article discusses how the task is initialized and implemented. 

Part I: Evolution of the routines 

I always find it interesting to know the background of the 
problem when exploring a programmingcxample. Mvexperience 
with implementing busy pointers went through three phases. 
The code fragments in Examples I, II, and 111 represent these 
phases Example I. Implementing a Busy Pointer 
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I he normal method of implementing a busy pointer is to 
create a sprite data structure and call SetPointerO when the 
program enters the busy state and ClearPomtcr( ) when the busy- 
slate is completed. The sprite structure requires space tor some 
system variables and a block of data defining the colors of each 
pixel. SetPointerO is an Intuition function that requires (headdress 
of the Window the busy pointer Is associated with, the address of 
the sprite data structure, and some sprite dimensions. 
ClearPointerO is another Intuition function that restores the 
system pointer to the window. 

To go beyond the Intuition ZZ cloud and create the illusion 
of movement, one needs a method of cycling through a sequence 
of images while in thebusy slate. My imagination for this program 
H as stirred by a spinning pointer example I found that required 
calling a routine every time the image was to change. Creating a 
sequence of sprite images is an artistic task and limited only by 
the graphics resolution and your imagination rhearra) ol sprite 
data [hat 1 designed for this program simulates a spinning disk 
andcanbe found in file "sprite.img". Example II. Simple Animation 
of the Busy Pointer. 
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Each lime through the busy loop, SetPointerf > is called ami 
the sprite index is incremented. As the while loop executes, the 
result is animation. I used this technique lor a short time, hut 
quickly tired of breaking up the busy code to insert SetPointerO 
calls to obtain a consistent animation action. Che rate ot action 
depends on the speed of the program going through the code, in 
some respect, this dependency is helpful. For instance, if the 
pointer changes every time a block of data is read from a disk, the 
pointer will spin faster when reading from a hard drive than from 
a floppy drive. I iowever. inmanvcaseMt is difficult (o determine 
when to change the pointer and discrepancies tnanima Hon speed 

can be distracting. With this in mind, I decided that cycling the 
pointer images was a job for the Amiga's multitasking abilities. 
Example 111. Multitasking Animated Busy Pointer 

■ ■ 
Spin_us«ci9: * - . ■. o seconds between imac> 
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• ■ 
■ 



er Data | j 



• 



The original simplicit) of starting the busy pointer before the 
busy code and restoring the pointer when finished is desirable. 
This is achieved with a task that cycles the pointer with a delay 

between images and responds to start and stop signals. Ibis 

approach eliminates inserting SetPointerO calls within the busy 
code. I he priority ol the cycling task Is used to make the cycle 

speed either dependent on the execution ot the code or a constant 

speed li thepriorit) I- lower than the busy code or the system is 

busy, the sluggish pointer animation illustrates this Whereas, ii 
the priority is set high, the pointer will cycle at a constant rale 

Since 1 chose my Sprite imagery to appear as a spinning ball, 
the name of the main program file is "SpinTask.c". As Stated 
earlier, the definition ol the sequence of sprite images is in file 
"spnte.img". File "Spawn.c" contains the code for the task that 
cycles through the pointer Images, but more on that later. For 
now. assume that the task exists and concentrate on how to 
communicate with it. I he listing of main program file Spml,isk A 
expands on the summary ol Example III Once this program is 
undersUwKl, the routines to implement multitasking busy pointers 
can be ported to other programs. 

PART 2: How to replace SetPointerO with a 
multitasking animated pointer. 

The first step in using these routines is lo open a window 
pointers are associated with specific windows. When the 
address ot the window is established, a task structure is created 
and linked to the w Indow by calling: 

* 

Each window that displays the busy pointer needs initial- 
ization with this function. Don't worry about multiple windows 
using the same task server code because each window will have 
Its own task structure. Each time a signal is sent to a task, the task 

server routine gets called with a stack pointer trom the task. In this 



way, the task server can be servicing several windows and yer,a) 

any given time.it deals onU' with a single window. The memory 
overhead for each window is the size of the task structure and task 
stack 

losimpliK the program. I use the window's UserData Held 
to hold the address of the task control block. It your program 
already uses the window's UserData held, .mother variable to 

hold the task address returned bv SpawnSpinl ask() is required. 

It SpawnSpinTaskO returns NULL, the task creation railed and 

the task should not be used. 

I he Spin usee variable is initialized with the time in mi- 
» n'M. unds between the pointer images InNTSC, the standard 
American display, the screen is updated 60 times per second 
which corresponds to 16.667 microseconds between updates 
Values of 30.000 to 90,000 microseconds are appropriate tor 

Spin_usec. The Priority variable determines the priority ol the 

faskand is initialized ton !u SpawnSpinlask(),whichisreasonable 
tor most programming practices Alter initialization, the pointer 
animation is started by sending a signal to the task via: 

Signal((struct Task *)WPtr->UserDala,SlGl SPIN); what 

ever action constitutes the bnsv action can now begin and the 
pointer animation will inform and amuse the use! while the 
Window is active When the busy actum is complete, I stop signal 
is sent to restore the svstem pointer 

■ 

The pointer can be controlled by sending start and stop 
signals until the program is read\ to exit Ik-lore quitting, eat h 
task control block should be removed bv calling 

■ * 

Thai's all there is to it. In summary— the task is initialized 
with SpawnSpinTaskO. Before starting the busy action, a start 
signal is sent with Signal)). When the busy action ends, the 
pointer is restored with a stop signal and the task is removed with 
KiIlSpinTask(). To illustrate how easily this can be done, 1 added 
set en lines to the Crunchy Frog II article by |im Fiore to imple- 
ment an animated busv pointer during his setup main(> 
functionfsee file Tasty Frog.add). 

PART 3: Spintask.c demonstration program. 

The rest of SpinTask.c simply initializes the gadgets ^ui 
wails foi gadget messages I he gadgets with II) fields of 
GAD_DELAYVALUE and GADJ'RIORITYVALUE are integer 
string gadgets They can be modified by the user to change the 
delay between images (how fast the ball spins) and the priont\ ol 
the task Selecting GAD_START will check the bounds of the 
delay and priority variables and signal the task lo spin using these 

parameters I here is no harm sending consecutive start signals 
Selecting GAD. STOP will signal the lask to stop spinning the 
pointer There isaisosomccodetoprocessGADGI 1 LP messages 
and move between string gadgets 

Since the main program just waits for gadget messages, it 
doesn't reallvevercise any busy code. Rather than addingartituial 
busy code, I left it to the user to run another program while the 
busy pointer is spinning. Don't forget that thebus) pointer isonlv 
displayed when the window is active. I ry opening a CI I window 
and typing "dirdfO: all" while Spin! ask is running with a delay 
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t>t 60 milliseconds and priority of -10 or « 10. Also, tr\' running* 
your programs and adjust the delay and priority values until all 
are appropriate. Use these values when you port the busy pointer 
into vour programs, ["he code is divided into files to enhance 
portability, I he imagery can be replaced with custom imager ml 
the routines can be linked to other programs with minimum 
hassle 

PART 4: How the task works 

The basic (unctions of the task are to call the SetPointerQ 
routine at specific intervals and respond to start, stop, and ter- 
minate signals The task begins by allocating SIC I STAR I and 
SlGF_STOP signals. For the terminate signal, I chose to use the 
SU .HRF \KF_CTRL_C signal, which is defined for all tasks. 

In order to change the pointer at regular intervals, a timer is 
needed implement a delay. Since the precision of spinning a 
pointer is quite low, I decided to open a UNIT_VBLANK timer 
il-\ ice using the vertical interrupt. This device has a resolution of 
♦ /- 16.67 milliseconds ,md very low overhead It doesn't make 
much sense to change the pointer faster than the screen gets 
updated. 

To use the timer device, you need to set up a timcrlOB 
menage linked to. i message port. The task sets up these resources 
betore going into a wait state. The remaining trick is to find the 
window associated with this task control block. Calling 
FindTask(NULL) returns (he address of the task structure and 
SpawnSpinTaskO has initialized the task lc_UserData field to 
a»"»»in t'-.- address of the window. 

Now it is a simple matter of wailing for either a timer 
message or a signal. lour signals can occur. 
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It Knot a simple matter because multiple signals can occur while 
the task is waiting. For example, start and stop signalscould occur 
beinri 1 the task hasachance to respond or a terminate signal could 
get sent while the timer is still counting down. 

I he following sequence works best tor me. First, handle the 
timer message. II it has not expired, cancel it. If it has expired, get 
the message trom the message port. Now, there is a subtle, but 
important, point. If the signal consists exactly of a timer signal, a 
new timer should be started. On any combination of signals, a 
new tuner should not be started At this point, theSIGF_PORT 
signal is cleared and the remaining signals arc handled. The 
animation is started if exactly the SIGF_START signal is set It the 
SIGF.STOP or S1GBREAKF_CTRL,C signals are received in 
conjunction with SIGF_START, a new animation should not be 
started. ClearPoinlerf) should be called when either SIGF.STOP 
or S!CBREAKF_CTRL_C signals are received. Finally, when a 
SIGBREAKF_CTRL_C signal is received, the function returns all 
of the resources it allocated. 

PART 5: Possible Enhancements 

If you can follow this article, you can use the spinning ball as 
a busy pointer in your programs. You can also design a more 



clever animation with your own custom pointer imagery. There 
are other pointer tricks that could make the busy pointer even 
more interesting. To make the busy pointer even more interest- 
ing, cycle the pointer colors or attach another sprite to display 
more colors. By changing the hot spot, the pointer animation can 
orbit about the hoi spot . The pointer animation could also be used 
when yourcode is in a state other than busy 

The technique of using a task to do an auxiliary job is an 
important part of programming in a multitasking environment. 
I Ins example shows how to receive signals, use the timer device, 
and process in the background. The task can be modified to do 
other jobs. As a final word, don't be afraid to experiment. I 
recommend keeping thespintask demo program around to quicklv 
determine proper delay and priority values. Have fun! 
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Listing Four 
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The remainder of thr liflinp- for Multitasking 

Animated lliisy Pointer can be found on 1 1 ■« - 

AC's TECH Disk 



Plfusi* write io: 
Jerry Truntow 
e/o AC'sTECH 
P.O. Box 2140 
Fall River, MA 02722-2140 
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—MenuScript continued from p. 63 



It turns out lh.it if we arc using C to parse the input, our task 
is made slightlyeosier if we allow only one statement per line. The 
reasons for this are easy to see. First, there is no need for a special 
end-of-statement character, for example, the semi-colon of C, so 
there Is one less special character to search for. Second, and more 
importantly. C already has tin- special function lgels( ) (found in 
<stdio>). which reads a single line of a tile Since we know that 
there is exactly one statement per line, we can use Igets( ) to read 
eadl statement trom thejnpul tile, one after the other. 

This point deserves a second look. Suppose we want to allow 
multiple statements per line, and the semi-colon is treated as an 
end-of-statemeni character Then a typical line of input might 
look like this: 

<line 1> menu "Menu I". item "item I"; — comment 
<hne 2> .menu 
<line 3> 
Menu 2"; — this is a continuation of <lme 2> 
■ end of file> 



'Buffer** n input_i-har; /'copy into buffer '/ 
I while (TRUE); 
return (TRUE); 



MenuScript's design was 

guided by two 

philosophies: a language 

for describing text menus 

should be simple and 

easy-to-use and control 

over fine detail should not 

be sacrificed for such 

ease-of-use. 



How might we parse this file 1 Fgetsl > is clearly out, since a 
single statement could span more than one line. We need to read 
only one statement at once, and copy that statement into an input 
buffer. What we could do is write our own statement-grabbing 
routine, which might look like this: 

BOOL Grab_a_Statcmcnt(FlLF input.char 'Buffer) 



unsigned char input_char; 
do 



of file V 



input_char = (unsigned char)fgetc(input); 
if (input.char == EOF) return (FALSE);/* end 

if (input_char == ';') break; /"end of statement 



We could then call Crab a_Statment( ) until it returned 
I'M Sl\ and after eadu all a new statement would he waiting for 
us in 'Buffer'. 

Obviously this is not a great deal of extra code for the 
anuenien.ee of being able to write more than one statement per 
line furthermore, almost all modern computer languages allow 
multiple-statement lines. MenuScnpt. though, is highly special- 
ized and not intended to bea general purpose Intuition program- 
ming language. It's not the next C++, and so to keep things simple 
its input I lies are really script tiles I his is a good general rule: the 
more specialized the purpose, the more you might consider 
making il a scripting language. 

Now we come to the most interesting and complex part of 
parsing. Once MenuScnpt has read a statement into some kind of 
input buffer, what next? In MenuScript there can beany amount 
of white space between the start of the line and the first command, 
and subsequent parameters are separated by spaces or commas 
We might wish to write a (unction which first skips over leading 
white space until it comes to a non-whitespace character and 
saves that position. Our function would then continue to scan 
over subsequent non-whitespacecharactcrs until it found a space 
or a comma (recall that thi*se characters term male commands and 
parameters). It would then return a pointer to the original first 
non-w hitespace character \\\> might also want il to remember 
where it is in the input from call to call, and to return NULL when 
it comes to the end of a line. Such a function would be just what 
we need to parse each statement, but it would be somewhat tricky 
to write and debug. 

The Good News 

Fortunately, we don't have to write this function ourselves. 
The standard C language implementation contains an obscure 
function called strtok( } which can be found buried in <string.h>. 
This function is precisely what we'vebeen looking for. MenuScript 
usesstrtok( ) extensive!) When it is parsing input lines 

I he first timesirtok) ) is called we give it a pointer to a buffer 
containing the string we wish to parse, and a pointer to a string of 
terminating characters. Starting at the first character of the buffer. 
strtok( ) compares each character of the terminating character 
string to each character in the buffer. When it finds a character 
that is not included in the terminating character string, it remem- 
bers that position in the buffer. It then continues to scan the buffer 
until a character that is m the terminating character string is 
found. The terminating character is overwritten with '\0\ and a 
pointer is returned to the original remembered position. If we 
wish to continue to parse the same line, then we would call strtok( 
) again with a 'Buffer' argument ofNULL.Strtokl) returns NULL 
when there are no more characters in the buffer to look at 

This is actually much simpler than it sounds. We can look at 
a >. isual representation of a string buffer and see what succes- 
sively calling strtok( ) does to il In the MenuScnpt language, a 
line of input might look like this 
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< .width 320 ;commenI > 

Our string buffer looks like this: 



W 



d t h _ 3 2 _ ; c o m m e n t n> 



Hen the underscores <J are spaces, and '\n' is the newline 

ch.i ratter. We wish to break the input line into the following 
pieces: <.width> <320><;comment>. Everything else in the line 
can be ignored. Let us set* how strtok( ) tan do this for us. 

On a line, a command can be preceded by any amount of 
white space. Also, a line may be completely blank. So the firsl call 
tostrlok() would be as follows, where Success isa BOOK variable: 

Success = sfrtok( Buffer." \x20\t\n"); 

(This example has been simplified for clarity Although 
MenuScript uses strtok( ) in much same manner as described 
here, the surrounding code has been eliminated so as not to 
obscure the point.) Note that the variable 'Buffer' is a pointer to 
the string whith you want to parse. 

Strtok( ) examines the first character of the buffer and com- 
pares it to each of '\x20' (space), '\t' (tab), and An' (newline). 
Finding it to be a space f\x20'), it moves on to the next character. 
also a space. Finally, after looking at the third character, it Finds 
a '.', which is not one of "\x20\t\n": 

<__.width_320_;commenl \n> 

This position is saved. ("'EPV— DRAW ARROW") 

Strtok( ) stores a pointer to the '.' character somewhere and 

continues to scan the string, but this time it will stop when it finds 
a character that is included in the terminating string. So it skips 
over the' w', 'i'. 'd\ T. and 'h' characters, stopping when it finds 
the space immediately after the 'h'. 



Strtok( ) points 'Buffer' to here ("M:PV— DRAW AR- 



ROW") 



<__.width_320_;comment \n> 

Stops here ("*EPV— DRAW ARROW") 

Now it overwrites this space with a NULL ('\0') and points 
'Buffer' to the period (.(character. The position of this terminating 
character is also saved so that on the next call strtok()can continue 
to scan from where it left off. 



Buffer' now points here <"*EPV— DRAW ARROW" 
<_. width \0 320 ;comment \n> 



This space is overwritten with AC ('"EPV— DRAW AR- 
ROW") 
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Notice al this point "Butter points to the string: ".width" (no 
more, no less), whith is exactly what we wanted. Strtok( ) has 
given us the first token of the input string, to process as we please 



In order to grab the next token wecallstrtokt, (again, but this 
time with a NULL argument for 'Buffer': 

Success = strtok{NULL,'Ax20\t\n"); 

It in the NL 1 1 argument which tells strtokl ) th.it wew ish !*< 
continue with the original string from the last call. 

Strtokl ) st.irts.it the next character after the 'Mr and repeats 
the above procedure. So after a second call to strtokl ), the string 
buffer looks like this 

'Buffer' now points here ("'El'V— DRAW ARROW") 

<__. width \0320 \0;comment \n> 



Stops here, and overwrites with A0' (' 
ROW") 



'EPV— DRAW AR- 



And similarly, after .1 third call: 

'Buffer' points here ('"EPV— DRAW ARROW 
<_ _ - w i d I h \0 3 2 \0 ; c o m m e n t \0> 
Stops here (•••EPV— DRAW ARROW") 



Since there is no more input, on the fourth call strtok( ) will 
return NL'l.l . and we are finished parsing this line. 

In the MenuScript source code you can find strtokf ) used in 
all of the sections which read input lines: main( ), GetName( ). 
ProcesslteniArgsi )..ind ProcessMenu( ). Note that CetNamef. ) is 
used to grab text that is enclosed in quotation marks, so that 
spaces can be included within quotes. 







The listings and all 

necessary files for 

MenuScript can be found 

on the ACs TECH Disk. 



Please write to: 

David Ossorio 

c/o ACs TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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OwMoping an AmigaDOS 2D 
Unt UUtlly 




; OrTremieri' ]SH»e 
Volume 1, Number 1 

Magic Macros with Resource bu IcffLavin 
Reconstructing MI'M data irom a hard disk. 
coping wilh library stubs, creating image 
.fata, and a few Other tricks thai can be done 
With Uw Resource disassembler and a few 
magk macros 

\nngiiliOS, I dit and f.Y, ursij .■ (Viiyriirn- 
mjny Trthnfouet bv Mark Pardue 
Creating a hard disk utility using only 
AmigaDOS commands and the EDTI line 
editoi (on disk) 

Building the VidCell 256 Grayscale 

Digitizer bu TaddEBMi 

Build an 8-bit 256 grayscale digitizer lor less 

than&so Includes schematics 

Am Introduction to InterProcess Communi- 
cation with ARexx by Dan Sugalski 
An Inside out step-oy-step look al what II 
takes to star! working with lit" and ARexx 

An Introduction to the I tl»». Library by Jim 

■ ■ 

Speed development with the dissidents' 

ll.BM rORM-specid. library 

Developing a Relational Database in C 
using dBC III ly Robert Broughton 
Developing .» database application using the 
I attkedBC 111 library 

Using Intuition's Proportional Gadgets 
from FORTRAN 77 In, Joseph R.t'j 
Using Absofts FORTRAN 77 to lake 

advantage oi most of the Amiga's ROM 

Kernal without wntmg extra C or assembly 

language imle. 

lastttoot: A Super BootBlock by Dan 

Babcock 

lastBoot is .1 IWBIock thai quickly loads 
an entire disk into memory, creates a RAM: 
disk, and boots imm that RAM: disk 

XntigaDOS for Programmers by Bruno Costa 
it you wanl lo delete liles. tmd OUl Hie ftiZCS, 
attributes or the amount of disk space, and 
even run processes trom inside vour 
program, read on! 

Adapting Mattel's Power Glove to your 
Amiga by Paul King and Mike Cabral 
Construct a special cable and write the 
necesary software in Modula-2 that will 

interface the Power Glove 10 the Amiga 



ACs TECH 
Volume 1, Number 2 

CAD Application and Design: Part I by Forest 

Arnold 

A detailed look at the mathematics and 

programing techniques used In CAD design 

Interfacing Assembly Language Applications 

to ARexx by Jeff Glatl 

How to add an ARexx implementation to a 

program. 

Adding Help to Applications Easily bu Philip 
S. Hasten 

Implement a context-sensitive on line help 
lacilit) in \ our applications 

Programming the Amiga s GUI in C—Part I 

by Paul Castonguay 

Oiling started inC Programming on the 

Amiga. 

Intuition and Graphics in ARexx Scripts bu 

leffGlatl 

Using the ARexx (unction library 
rx.intui- library which adds a few do/en 
ARexx commands thai allow an ARexx script 
to Utilize Intuition and Graphics routines 

USIX and the Amiga by Mike Hubbart 
A different introduction lo UNIX tor the 
Amiga programmer 

A Meg and a Half on a Budget by Bob Blkk 
Add 512K of RAM to your 1MB Amiga 500 
for about $30. 



ACSTiril 
Volume I, Number 3 

CAD Application and Design Pari II by Forest 
Arnold 

Develop an event-dri ven program which will 

let us move, resize, and rotate objects. 

C Macros for ARexx by David Black-well 
Accessing Ihe full power of ARexx from C. 

VHROM: Assembly Language Monitor ly 
Dan Babcock 

Explore your Amiga wiih this unique and 
Interesting Assembly Language monitor. 

Tlie Development of an AmigaDOS 2.0 

Command line Utility by Bruno Costa 
Using the new features of AmigaDOS 2.0 
develop the TO' command line utility 
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See what you're missing? 



Programming the Amiga's GUI in C — Part 

III by Paul Castonguay 
Create your hrst window 

Programming for HAM-L by Hen William 

An introduction to l hi" libraries and tech- 
niques required to program lor the HAM 1 
display 

Using RawDoI'mt in Assembly In/ feffLavin 
Print formatted strings easily and t 
wasting time rolling your own code 

Configuration Tips for SAS-C by Paul 

Costonguay 

Configure your system tor maximum 

performance with SA&4 

Iik-smim; tin Math ( d/ifiiii -m" troni HASH 
I'vK P, HanUihl 

Using libraries, access the Amiga's main 
coprocessor from AmigaBASlC. 



AC'S TECH 

Volume 1, Number 4 

GPJO— Low Cost Sequence Control by Ken 

Hall 

Take control of your Amiga with this Video 

Toaster-inspired General Purpose Interface 

Programming with the ARexxDB Records 
Manager by Benton fadtKM 
Learn to use this powerful ARexx database 
engine by creating a phonebook /auto dialer 
for use with the popular shareware te l ecom- 
municalions program VLT. 

T7ir Development of a Ray Tracer by Bruno 
Costa 

The first of a two-part series featuring the 
theory and application design of a full- 
featured implementation ol in open-ended 
ray-tracing package 

Programming the Amiga's GUI in C—Part 

III by Paul Caslonguay 
Paul continues his popular tutorial series 
with handles, structuring display modules, 
an introduction to programming graphic 
images and much more' 

Using Interrupts for Animated Pointers In/ 

\effLavm 

Jeff demonstrates a better way to animate 
pointers as well as the proper use of two 
types of interrupts 



Language I Mentions- -Strings ot /«/>< 
StringS by jimmy Hammonds 
An introduction to the implementation ol 
strings ,>t type StringS using C constructs 



AC'S TECH 

Volume 2, Number t 

Spartan — Build your Own SCSI Interface tar 
your Amiga SOW WOO by Paul tUrktl 
Stop swapping disks and build this Inexpert' 
sive and complete hard drive project. 

CAD Application and Design Part III (»y 
Forest Arncld 

Develop an architecture tor implementing 
geometric objects as true object-oriented 

objects. 

Implemlnting an ARexx Interface in yourC 
Program by David Blackuvll 
Part one ot a Structured approach to adding 
ARexx capabilities to jrour application 
written in G 

Programming the Amiga in bSOxO Assem- 
bler— Part I by William P. Nee 
l.earn to program the Amiga in 680x0 
assembler. Includes AMK assembler on disk! 

Programming the Amiga's GUI in C— Part IV 
by Paul GutongUMy 

The popular programming tutorial continues 
with taster draw routines 

Programming a Ray Tracer in C — Part II by 

Bruno Costa 

The practical use of illumination model 

Iheor) 

Low-Level Disk Access in Assembly by Dan 
Babcoek 

Develop an easy-to-use set of routines foi 
performing floppv access u ithoul the aid ot 
the operating s\ stem. 

To order call 1 -800-345-3360 now! 



Get any ACs TECH Back Issue for 
just $14.95 each! 

Also, for a limited time only, The 

ACs TECH Volume 1 (Complete 

Set) is available for just $45.00! 
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Developer's Tools 



Starting, with the next issue, AC> II XH for the Commodore Amiga will be featuring .1 special section for Amiga developers 
and those who wish to develop commercial products. This section wil give positive insights Into the industry as well as much needed 
information on the latest development tools, steps to a commercial product, licensing, marketing, finances, and business productivity 
Thissectionwillbedevoted to helping you develop your Amiga and your business into a profitable, efficient,and enjoyable investment. 

This issue, we are featuring a product section with some of the latest and best programming and de\ elopment packages 
available (or the Amiga 



AMOS PD 

Mark Scott at the Software Exchange la the AMOS I'D librarian in 
America. Hundred* of disks are in the collection, packed lull of AMOS 
Bask code for the beginner or expert AMOS America is the club name 
and we work directly with the U.K. librarian We are abo suppliers of 
AMOS Ikensewan Call for more inform.) I ion .nut .1 free AMOS PD 
catalog, l-9$4.95eachj 10-24 $3.95; 25. $2»s Runs on any Amiga. 
AJvK >S Bask programming language. 

ire Exchmg*J6lOGeo^ Washington Bfod - 67211.(316) 

685-4763 

AMOS-Thc Creator 

A sophisticated, yet easj <o-use development language for the Amiga 

with more than 500 commands which allow you to access the awesome 

power of the Amiga. MTSC/PAL compatible • 

Europress Softuure, Europa Houte, Arlington Park. MacclafieM, Cheshire. 

I ngfmd SK10 4NP. <Ull>44o2-585-9333 

Alien 

Implementation oi Rl-.XX.a high-level language especially suited for 

string manipulations and ,is .1 macro processor S 49.95 
William S. Hawes, P. O. Box 308. Maynard. MA. » 

AssemPro 

Bridge the gap between slow higher-level languages and ultra-fast 

machine language programming; AssemPro Amiga unlocks the full 

power of the Amiga's MH.XX) processor. It's a complete developer'-, kit 

for rapidly developing BUM rune language assembler pmgrams on 

your Amiga. ISBN 1-55755-030-1 S" 

Abacus Software. 5370 52nd &■ rand Rapids, Ml 49512. '6it>j 

698-0330 

Benchmark Modula-2 

Integrate*! compiler, linker, and I MACS editor Compiles at 10.000 

lines per minute with burst speeds of up to 30.000 lines/minute 

Libraries support AmlgaDOS. Intuition, Excel, and Modula-2. With 700 

'. d 0eument.1t ion Many demonstration programs. S199.95 
Awnf-Gflru> Software. 2213 rVoadbum, Piano. TX 75075. (2141 9640260. 

Developer System with Source Debugger and Library Source 

rhe complete Developer System combined whh Source I evd 

Debugger and Ljbrarj Source .ill for one price. S724 

Manx Safin,: P.O.Box 55 -j.SI. 07702. (800) 221- 

0440 

Rexx Compiler 

Compiles code that is ARe» compatible It makes the Rexx program 
Faster, ^mi eliminates external library look-up bv resolving library 

(unction calls and compile time I he Rexx Compiler .read 1 -, reentrant 
code, allowing users to make programs resonant 01 as part ol a 
support library I s,. the Rexx support library. Rexx math library, and 
Rexx Plus 1 ibr.iry (unctions as built-in (unctions ( all Rexx programs 
directly from other languages Use the compiler listing generated to 
find constant, symbols, and nesting levels Find refe r ences to B) mbols. 
Constants, and labels with the cross- reference produced Find logie 



errors in the Kew program by using nesting levels and additional error 
messages Find most errors with .1 single compile Use Rexx variable 
interlace to access symbols set trom hosl The programs that have been 
compiled can be invoked directly from Workbench, horn the CI 1 as >> 
command, or from am host 2X1 compatible Available December 1991. 
SI 50 

/ .lnwrjs Croup.l$785 West / wetw Miff Koj«f. Sit. 305 
3, 1 31 3)352-4288 

SAS/C ru Development System 

SAS/C Compiler Development system .uters a complete program- 
ming environment with SAS/C Compiler, global optimizer, blink 
OverU) linker. LSE screen editor, source-level debugger, comprehen- 
sive documentation, and more Release- 5 10 is Version 2 compatible 
ODD tut 

SAS Institute Inc.. One SAS Circle Box 8000, Carv. SC 27513-2414. (919) 
677-8000 

XII Programmer's System for the Amiga 

IX-velop XI I applications under AmigaDOS. Source code compatible 

with XII release J or UNIX-based machines Works u ith C.fx Base's XII 

window system for the Amiga Contents; Xll R J include files, xlib 

■then* Widjets, xtoolkil, xmu, BSD socket library networks: elhemet 

DECnet (TSSnet) .CP/1P(NE225).SAN.V arcnet and slip Requires 

Utthx5.10, } MB RAM 

i :t\ Base.1881 tiluvtt Drive. Milpilas. CA. 99 

AmigaMOPTost Management Package Version 2 

The AmigaMOl* V2 is .1 data management and user interlace tor 
electronic test systems. I inkable and run- time libraries are Included for 
writing the test programs and data handlers Other features Included 

in this version are safe memory support, dual multitasking/multiplex- 
ing test programs, and a help feature. $349 
Go Sofluvr,; rr*i Box 442 Spurt Road. Thompson, CT 06277. (X 
■ ■ 

Source Level Debugger (SDB) 

Interacts e source-level debugger designed for fast response and ease 
in debugging SDH lets user display all function action names; display 
Values 01 passed parameters, examine values from any active function. 
Customize the debugging environment with reusable command 
macros <\u^\ procedures; use function or line-by-line tracing, set 
breakpoints by Lines functions or variables; see actual l source as it 
executes; and more $12^ 

Manx Software Systems P Box SS, Shrewsbury, ty 07702.(800)221- 
0440 



Questions, comments or suggestions? Write to: 

Developer's Tools 

do ACs TECH 

P.O. Box 2140 

Fall River, MA 02722-2140 
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AC'S TECH 



• 




High 

Resolution 

Output 

fromyourAMIGA Tf 
DTP & Graphic 
Documents 



You've created [he perfect piece, now you're looking for a good service bureau for output. You want 
quality, but it must be economical, l-inulh. and most important.. you have to liml a service bureau that 

recognizes your AMIGA file formats. Your search is over. Give us j call! 

We'll imagesci your AMIGA graphic files to RC Lasei Paper or lilm at 2450 dpi (up to 154 Ipi) at a 

evtremcK competitive cost. Also available at competitive cost are quality Duponi ChromaCheck™ 

color proofs of your color separations/films. We provide a variety ofpre-press sen ices for the desktop 
publisher. 

Who are we? We are a division ol PiM Publications, the publisher of Amazing Computing for the 
Commotion W1H, A. We have a staff that really knows the AMIGA as well as the rigid mechanical 
requirements of primers/publishers. We're a perfect choice for AMIGA DTP imagescuing/pre-press 
sen ices. 



We support nearly every AMIGA graphu A DTP formal as well as most Mat intosh™ graphic/DTP 
formats, 



For specifu format information, please call. 



For more information call J -800-345-3360 

Just ask for the service bureau representative. 



The Next Generation In Backup Software 



Quarlerback 5.8 
] Quarterback 



; 1992 Central Coast Software 



Backup in progress. ciSysten? 

G3C 



/« Backup started Feb 11, 1992 at 1B:55:B2 HM •*• 



[□Id 



Pause Bbort 



HDFB: Writing B1 

W1 : N' 
:.:DF2: Ready 
SDF3: Ready 

Conpleled: 



4x 



Files: 
Bytes: 

I,, W d: 



25 
178.568 



Files: 
Bytes: 



559 
•4,599,613 



□ HddBuffers 

□ Assign 

2 Hv ^ • i 

□ BindOriwers 
J Break 

^ Change laskPr i 

□ ConCI ip 

SSP 

5 Date 

□ Delete 
jDir 

U DiskChange 

□ OiskDoctor 
QiskSalv 




I Ed 
"Udit 



Eva I 

Execute 

Fi lenote 

IconX 

Info 

Install 

IPrefs 



» 



/A.' fastest backup and archiving prat/ram on the Amiga! 
Supports up to four floppy drives for backup and r. 

New integrated streaming tape support 
\tu (' vnpression " option for backups 

Optional password protection, ui/h encryption, for data 
security 

Full tape control for retension. erase and rewinding 

New "interrogator, " retrieves da ice information from 

SCSIdei 

Capable of complete, subdirectory-only, or selected-files 
backup and restore 

Impnnvd wild card and pattern matching, tor fast and 
easy n leitive archiving 

Restores all date and time stamps, tile notes, and 
pnttection bits on tiles and directories 

Supports both hard and soft links 

Full macro and AltFXX support 

Full Workbench _'." compatibility 

Improved user interface, with Workbench 2.0 style ">'-/>' 

appearance 

Many more feature*.' 



Thousands of people rely on Quarterback 
for their backup and archival needs. Now. 
with Quarterback 5.0, there is even more 
reason to do so. Greater speed, even more 
features, and proven reliability. And a 
new "3-D" user interface puts these 
powerful capabilities at your finger tips. 
With features like these, it is no wonder 
that Quarterback is the best selling 
backup program for the Amiga. Would 
you trust your data with anything less? 



. \ 






Central Coast Software 

1 Dktiioa i if Xttr HorUorn Sottuwt, tnc 

206 Wild Basin Road, Suite 109, 
Vustin, Texas 787 16 

i JI.') :i2N -lirt.Sn • I'.W (512) :t2s-192.» 
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